cn-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cn-writing 中文技术写作规范

cn-writing Chinese Technical Writing Guidelines

适用于中文技术文章、个人笔记、需求文档和更新记录。目标是信息准确、行文简洁，便于阅读与审阅。

动笔前通读本文件；写完逐项复验（见「复验清单」）。

Applies to Chinese technical articles, personal notes, requirements documentation, and changelogs. The goal is accurate information and concise prose that is easy to read and review.

Read this document before writing; when finished, verify each item (see the “Review Checklist”).

一、标题规范

1. Title Guidelines

标题是信息，不是广告：直接说主题（「给 Astro 静态站加 R2 内容 API」），不写「我的博客改造之旅」这类空壳标题
不标题党：否决「一文读懂」「必看」「震惊」「高效搞定一切」等夸张词
不含糊：不用「关于 X 的一些想法」「随便聊聊 X」这种说了等于没说的标题
长度：博客标题建议10~25字；技术文档按检索和辨识需要命名，不强求固定字数。
日期与编号：博客日期交给发布元数据管理；需求编号、版本或日期有辨识作用时可保留。
是记忆索引：未来凭标题要能想起这篇讲了什么；读者（未来的自己）点开前就能判断值不值得读

Titles convey information, not advertising: State the topic directly (“Add an R2 Content API to an Astro Static Site”), rather than using an empty shell title such as “My Blog Transformation Journey”
No clickbait: Reject exaggerated phrases such as “Everything You Need to Know in One Article,” “Must Read,” “Shocking,” or “Solve Everything Efficiently”
No ambiguity: Do not use vague titles such as “Some Thoughts on X” or “A Casual Chat About X” that say almost nothing
Length: Blog titles should contain 10–25 Chinese characters. Name technical documents according to search and identification needs; a fixed character count is not required.
Dates and numbering: Leave blog dates to publishing metadata. Keep requirements numbers, versions, or dates when they help distinguish the document.
Act as a memory index: The title should help you recall what the article covered in the future. Before opening it, readers—including your future self—should be able to judge whether it is worth reading

二、行文硬约束

2. Hard Constraints for Prose

每段内容生成后逐项自检，全部通过才算合格：

简洁：一句话能说清的不用一段话。每个段落只承载一个核心信息点
明了：技术概念首次出现时用一句话解释，不假设读者已掌握。复杂流程用有序列表拆解，不堆砌成段落
不说废话：套话、客套、铺垫、总结性重复一律不写。开头直接进入内容，结尾不写空总结
流畅：按读者需要安排信息，段落衔接自然，不强套「是什么、为什么、怎么做」的顺序。
用词规范：术语准确且通篇一致；渲染与绘制、构建与编译含义不同，按实际行为选词。
可读性：正文每段围绕一个信息点，过长时按语义分段；不以 Markdown 源码的换行数判断段落长短。关键操作步骤用有序列表，配置或代码用代码块，适当加粗关键结论。

After drafting each piece of content, check every item below. It is acceptable only when all checks pass:

Concise: Do not use a paragraph when one sentence is enough. Each paragraph should carry only one core point
Clear: Explain a technical concept in one sentence when it first appears; do not assume the reader already knows it. Break complex processes into ordered lists instead of compressing them into paragraphs
No filler: Remove clichés, pleasantries, preambles, and repetitive summaries. Start directly with the content and do not end with an empty recap
Smooth: Arrange information according to the reader’s needs and connect paragraphs naturally. Do not force every text into a “what, why, how” sequence
Precise terminology: Use accurate terms consistently. Rendering and drawing, and building and compiling, have different meanings; choose the term based on the actual behavior
Readability: Keep each paragraph focused on one point and divide long passages by semantic boundaries; do not judge paragraph length by the number of line breaks in the Markdown source. Use ordered lists for key procedural steps, code blocks for configuration or code, and bold key conclusions where appropriate

三、避免空泛表达

3. Avoid Vague or Generic Expressions

以下表达在只起填充作用时删去；必要的事实对比、引用和反例不作机械禁词匹配。

万能开头：「在当今」「随着…的发展」「近年来」「众所周知」「随着互联网的普及」
AI 填充词：「值得一提的是」「值得注意的是」「需要注意的是」「其实」「实际上」「显然」「不难发现」「综上所述」「总而言之」
机械连接：空转的「首先…其次…最后…」「一方面…另一方面…」（真正有并列关系时才可用）
修辞问句过渡：「你知道吗？」「为什么会这样？」「答案很简单：」
元叙述：「本文将介绍」「接下来我们来看看」「下面开始」——不预告自己写什么，直接写
名词化动词：「进行了优化」→「优化了」；「做出改变」→「改了」；「加以说明」→「说明」

Delete the following expressions when they merely fill space. Do not apply mechanical keyword bans to necessary factual comparisons, quotations, or counterexamples.

Universal openings: “In today’s world,” “With the development of…,” “In recent years,” “As is widely known,” “With the spread of the internet”
AI filler phrases: “It is worth mentioning,” “It is worth noting,” “It should be noted,” “Actually,” “In fact,” “It is obvious,” “It is not difficult to see,” “To sum up,” “In conclusion”
Mechanical transitions: Empty transitions such as “First… Second… Finally…” or “On the one hand… on the other hand…” should only be used when the content has a genuine parallel relationship
Rhetorical-question transitions: “Do you know?” “Why does this happen?” “The answer is simple:”
Meta-narration: “This article will introduce…,” “Next, let’s take a look…,” “Let’s get started…” Do not preview what the text is about to say; state it directly
Nominalized verbs: Prefer direct verbs over nominalized constructions: 「进行了优化」→「优化了」 (conducted an optimization → optimized); 「做出改变」→「改了」 (made a change → changed); 「加以说明」→「说明」 (provided an explanation → explained)

四、结构约束

4. Structural Constraints

短文/随记：1-2 段成文，不设小节，直接说事
文章：每节只围绕一个子主题；h2 标题是信息本身，不用「前言/正文/结语」这类骨架词
段落与列表：简介用段落，并列事项用同级列表，从属细则用子列表；不为格式统一把所有内容列表化，层级按实际适用范围划分。
结尾：不写空总结；要收尾就写一句新的判断或落点，不复述上文
观点与事实分离：事实直接陈述；观点明确是观点，不装成事实
确定就确定：能确定的不用「大概/似乎/可能」软化；数据、版本号、日期不编造
一个点只说一次：标题、正文、图片说明不互相复述
语气：可以带个人语气但克制——不套近乎、不加 emoji、不用网络流行语；观点直接陈述，不拿「我个人认为」开头

Short essays and notes: Use 1–2 paragraphs, without subsections, and state the matter directly
Articles: Keep each section focused on one subtopic. Make h2 headings informative in themselves rather than using structural labels such as “Foreword,” “Body,” or “Conclusion”
Paragraphs and lists: Use a paragraph for the introduction, a same-level list for parallel items, and child lists for subordinate details. Do not turn everything into a list merely for visual consistency; structure the hierarchy according to each item’s actual scope
Ending: Do not write an empty summary. If the text needs a closing, end with a new judgment or conclusion rather than repeating the preceding content
Separate opinions from facts: State facts directly and make it clear when something is an opinion; do not present opinions as facts
State certainty when certainty exists: Do not weaken something you know with “perhaps,” “possibly,” or “probably.” Do not fabricate data, version numbers, or dates
State each point once: Do not repeat the same point in the title, body, and image caption
Tone: A personal tone is acceptable but should remain restrained. Do not sound overly familiar, add emoji, or use internet slang. State opinions directly rather than beginning with “In my opinion”

列表使用

List Use

列表类型由内容关系决定，不为视觉统一或凑条数编号。

有序列表：表示执行步骤、明确优先级或排名；调换顺序会改变含义时使用。
无序列表：表示并列要求、分类、条件分支或从属细则，阅读顺序不影响含义。
复选列表：用于需要逐项勾选完成情况的检查清单，不用于一般说明。
单个要点：能概括时写作「概括：具体说明」；普通短句不强加标签。
多个细则
- 父项只写「概括」，具体要求全部放入子列表。
- 不在父项先写一条要求，再用子项补充其他并列要求。
层级与缩进
- 独立要求同级，从属要求缩进；子列表按自身关系选择有序或无序。
- 通常两层足够，避免把全局要求放入局部条件下。

Choose the list type according to the relationship between items. Do not number items merely to create visual consistency or add bulk.

Ordered lists: Use them for procedural steps, explicit priorities, or rankings, especially when changing the order changes the meaning
Unordered lists: Use them for parallel requirements, categories, conditional branches, or subordinate details whose reading order does not affect the meaning
Checklists: Use them for items that must be checked and completed individually, not for general explanations
Single point: When a point can be summarized, write “Summary: specific explanation.” Do not force a label onto an ordinary short sentence
Multiple details
- Write only “Summary” for the parent item and place all specific requirements in child lists
- Do not write one requirement under the parent and then use child items to add other parallel requirements
Hierarchy and indentation
- Keep independent requirements at the same level and indent subordinate requirements. Choose ordered or unordered child lists according to their own relationships
- Two levels are usually sufficient. Avoid placing global requirements under local conditions

五、数字、术语与标点

5. Numbers, Terminology, and Punctuation

数字与术语

Numbers and Terminology

标识符原样：版本号、命令、包名、文件名、函数名一律原文，不翻译（
```
astro check
```
不写「星体检查」）
技术单位用原文：MB、ms、Hz 保留不译；中文量词用中文（一个、两个）
参数用阿拉伯数字：512MB、1-2 分钟、第 3 步；不用「五百一十二 MB」
中英文混排：中英之间空一格；命令或代码标识符两侧不硬塞空格，与 markdown 内联代码配合
大小写保持原样：代码标识符的大小写在正文里不动

Keep identifiers verbatim: Never translate version numbers, commands, package names, file names, or function names (write
```
astro check
```
, not 「星体检查」)
Keep technical units in their original form: Retain units such as MB, ms, and Hz. Use Chinese measure words for Chinese quantities (一个、两个)
Use Arabic numerals for parameters: Write 512MB, 1–2 minutes, and Step 3; do not write “five hundred and twelve MB”
Chinese-English mixed text: Put one space between Chinese and English text. Do not force spaces around commands or code identifiers; use Markdown inline code instead
Preserve capitalization: Do not change the capitalization of code identifiers in the body text

标点规则

Punctuation Rules

中文叙述使用中文标点，括号使用半角

()

；代码、路径和命令内部的符号保持原样。

句子标点（，。、：；？！）：中文叙述中一律全角。半角逗号
```
,
```
只出现在代码里
顿号：中文列举一律用顿号
```
、
```
，不用半角逗号：
```
SystemMaxUse=50M
```
、
```
SystemKeepFree=256M
```
括号允许半角：中文句子里的括号统一用半角
```
()
```
（装代码参数时更贴近代码），全文不要混用全半角
引号：中文引用用「」；代码不套引号，交给反引号——禁止
```
"caddy reload"
```
这种拿双引号包代码的写法
标识符内部原样：
```
=
```
、
```
/
```
、
```
.
```
、
```
-
```
、
```
_
```
属于代码，不动
整句都是代码/命令：保持原样，不套全角规则（代码块内更是原样）
Markdown 语法不受影响：表格
```
|
```
、frontmatter YAML、代码块内容都按原样

示例对照：

❌ 现在这样	✅ 规范后
新增 2G swapfile(swappiness=30),写入 fstab	新增 2G swapfile(swappiness=30)，写入 fstab
设 SystemMaxUse=50M,SystemKeepFree=256M	设 `SystemMaxUse=50M` 、 `SystemKeepFree=256M`
journald 没设上限,悄悄占掉 1.1GB。	journald 没设上限，悄悄占掉 1.1GB。
用 "caddy reload" 热加载	用 `caddy reload` 热加载

Chinese prose uses Chinese punctuation, while parentheses use half-width

()

. Keep symbols inside code, paths, and commands unchanged.

Sentence punctuation (，。、：；？！): Use full-width forms throughout Chinese prose. The half-width comma
```
,
```
appears only in code
Enumeration comma: Use the Chinese enumeration comma
```
、
```
for Chinese lists, not a half-width comma:
```
SystemMaxUse=50M
```
、
```
SystemKeepFree=256M
```
Half-width parentheses are allowed: Use half-width parentheses
```
()
```
consistently in Chinese sentences; they are more suitable for code parameters. Do not mix full-width and half-width forms
Quotation marks: Use 「」 for Chinese quotations. Do not wrap code in quotation marks; use backticks instead. Never write
```
"caddy reload"
```
with double quotation marks
Keep identifiers unchanged: Do not modify symbols inside identifiers, including
```
=
```
,
```
/
```
,
```
.
```
,
```
-
```
, and
```
_
```
Sentences consisting entirely of code or commands: Keep them unchanged and do not apply full-width punctuation rules, especially inside code blocks
Markdown syntax is unaffected: Keep tables
```
|
```
, frontmatter YAML, and code block contents unchanged

Examples:

❌ As written	✅ Standardized
新增 2G swapfile(swappiness=30),写入 fstab	新增 2G swapfile(swappiness=30)，写入 fstab
设 SystemMaxUse=50M,SystemKeepFree=256M	设 `SystemMaxUse=50M` 、 `SystemKeepFree=256M`
journald 没设上限,悄悄占掉 1.1GB。	journald 没设上限，悄悄占掉 1.1GB。
用 "caddy reload" 热加载	用 `caddy reload` 热加载

六、代码与示例

6. Code and Examples

代码块标记语言：
```
```typescript
```
等；行内代码用单反引号
只贴关键部分：不贴脚手架和无关上下文；完整文件用「文件路径 + 要点」或链接带过
示例输出要真实：不编造终端输出；示意性质的要明确标注「示意」
代码说明：按需说明用途和结果；上下文已清楚时，不强制在代码前后各补一句。

Mark code block languages: Use markers such as
```
```typescript
```
; use single backticks for inline code
Include only the relevant parts: Omit scaffolding and unrelated context. For complete files, use the file path plus key points, or provide a link
Use real example output: Do not fabricate terminal output. Clearly label illustrative output as “Illustrative”
Explain code as needed: Describe its purpose and result when necessary. If the context is already clear, do not force an explanation before and after the code

七、Markdown 源码换行

7. Line Breaks in Markdown Source

源码换行服务于编辑器阅读和 Git diff，段落长短服务于渲染后的阅读。二者分别检查。

语义断行
- 优先在句号、分号或自然分句处换行，不为凑行宽接入下一句。
- 每行约40~60个汉字作为参考，混排不机械计数。
渲染换行：同一段内使用普通换行，不为控制源码行宽添加行尾双空格或
```
<br>
```
。
语法完整
- 不切断词语、行内代码或链接，列表续行保持正确缩进。
- 标题、表格、代码块、长链接和 YAML frontmatter 不强制折行。
编辑范围
- 遵循仓库已有 Markdown 格式化配置，不为行宽擅自修改配置。
- 只整理本次涉及的段落，全文重排作为独立排版任务处理。

Source line breaks support readability in the editor and in Git diffs; paragraph length supports readability after rendering. Review them separately.

Semantic line breaks
- Prefer breaking lines after periods, semicolons, or natural clause boundaries. Do not pull the next sentence onto the current line merely to fit a target line width
- Use approximately 40–60 Chinese characters per line as a reference, but do not count mechanically in mixed-language text
Rendered line breaks: Use ordinary line breaks within the same paragraph. Do not add trailing double spaces or
```
<br>
```
solely to control source line width
Syntactic integrity: Do not split words, inline code, or links, and maintain the correct indentation for continued list items. Do not force line breaks in headings, tables, code blocks, long links, or YAML frontmatter
Editing scope: Follow the repository’s existing Markdown formatting configuration and do not change that configuration merely to control line width. Reformat only the paragraphs involved in the current task; treat a full-document reflow as a separate formatting task