zh-tech-writing

中文技术文档写作

目标：写出像资深工程师写的中文技术文档。平实、具体、短句。

流程

写新文档：

1. 先想清楚读者是谁，读完要能做成什么事。一句话说不清，先问用户。
2. 按下面的“句子”“语气”“段落与结构”“排版”写。
3. 自检：拿“AI 腔清单”逐条对照全文，命中的全部改掉。
4. 跑 autocorrect --fix <文件>，修空格和标点。命令不存在就跳过，改为按“排版”手动检查。
5. 手动检查 autocorrect 管不到的：引号、省略号、破折号。

修改已有文档：

1. 通读全文，再动手。
2. 用户只要意见：按“原句 → 改后 → 原因”列出问题，不改文件。
3. 否则直接改，然后做上面的第 3～5 步。最后用两三句话说明改了哪几类问题。

每一步都做完才算完成。第 3 步的标准是：清单每一条都对照过，全文没有命中。

句子

• 用逗号隔开的每一截，尽量在 20 字以内。超过 30 字就拆开。整句不超过 100 字。
• 一句只说一个意思。多用简单句和并列句，把长定语拆出去。
• 差：那个昨天生病的人没有参加会议。
• 好：他昨天生病了，没有参加会议。
• 用肯定句，不用双重否定。
• 差：请确认没有接通装置的电源。 → 好：请确认装置的电源已关闭。
• 差：没有删除权限的用户，不能删除此文件。 → 好：用户必须有删除权限，才能删除此文件。
• 用主动语态，少用“被”。
• 差：假如此软件尚未被安装 → 好：假如还没安装这个软件
• 动词直接用，不套“进行”“做出”。
• 差：对配置文件进行修改 → 好：修改配置文件
• “这”“其”“该”只指一个明确的对象。可能有歧义就把名词重复一遍。
• 名词前的修饰语不超过两层，多了就拆成两句。
• 用现代汉语常用词，不用文言、生造词。
• 差：这是唯二的方法。 → 好：只有这两种方法。
• 分清“的、地、得”：开心的笑容、开心地笑、笑得开心。

语气

• 像给同事讲清楚一件事：口语化可以，网络流行语不用。
• 称呼读者用“你”，称呼项目方用“我们”。
• 用陈述语气，句末用句号。
• 用事实代替形容词：给出数字、命令、文件名、报错原文。
• 差：性能得到了大幅提升。
• 好：p99 延迟从 120 ms 降到 40 ms。
• 确定的事直接说。不确定就说清楚哪里不确定、怎么验证。

段落与结构

• 每段第一句说这段的重点，后面的句子为它服务。一段一个主题。
• 一段最好不超过 4 行，最多 7 行。
• 标题用二级、三级为主：
• 一级标题下直接接二级，不跳级。
• 同级标题只有一个时，去掉这层标题。
• 下级标题不重复上级标题的名字。
• 需要四级标题时，改用 **（1）xxx** 或列表。
• 标题末尾不加句号、逗号、冒号。
• 列表只放真正并列、可以单独扫读的条目。有因果、转折关系的内容，写成段落。
• 加粗只给读者必须注意的警告或关键词，一屏最多一两处。
• 引用别人的内容或图片，注明出处。

排版

每篇都要守的规则：

• 中文与英文、数字之间加一个半角空格：在 Linux 上安装 5 个包。
• 中文句子用全角标点：，。：；？（）。整句是英文时用半角标点。
• 英文、数字后面紧跟全角标点时，中间不加空格：他用的是 MacBook Air。
• 引号用全角 “ ”，引号里再套引号用 ‘ ’。
• 并列的词用顿号 、 隔开，最后一项用“和”连接：Google、腾讯和百度。
• 省略号写成 ……，不写 ... 或 。。。，也不和“等”连用。
• 数字一律用半角。

数字（千分位、单位、范围、倍数）、括号、冒号、连接号、英文缩写的细则，见 references/typography.md。文档里出现这些内容时读它。

写一整套产品手册或文档站、需要规划目录和文件名时，读 references/manual-structure.md。

AI 腔清单

自检时逐条对照。左边是要找的写法，右边是改法。