中文技术文档的写作规范

概述

---

这个是阮一峰老师的中文技术文档的写作规范，希望对自己写博客有所参考。下面只整理了一些特别需要注意的。

标题

---

尽量不要使用四级标题，防止文章的层次太多、太复杂。四级标题只适用于篇幅比较长的文章。对于三级标题下的并列内容，建议只使用项目列表（Item lis）。

错误：
### 三级标题
#### A
#### B

正确：
### 三级标题
**（1）A**
**（1）B**

文本

---

字间距

（1）全角中文字符和半角英文字符之间应该有一个半角空格。

错误：这是Windows系统。
正确：这是 Windows 系统。

（2）半角英文和阿拉伯字符，与全角标点符号之间不留空格。

错误：这是我的 MacBook 。
正确：这是我的 MacBook。

句子

（1）尽量使用简单句，避免使用复合句。

复合句：那个昨天生病的人没有参加会议。
  
简单句：那个人昨天生病了，没有参加会议。

（2）同一个意思，尽量用肯定句表达，不用否定句。

肯定句：请确认装置的电源已经关闭。

否定句：请确认没有接通装置的电源。

（3）避免使用双重否定句。

错误：没有权限的用户，不能删除这个文件。
正确：拥有权限的用户，才能删除这个文件。

写作风格

（1）尽量不使用被动语态，改为使用主动语态。

错误：假如此软件尚未被安装，

正确：假如尚未安装这个软件，

（2）名词前不要使用过多的形容词。

错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。

正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。

段落

---

原则

• 一个段落只能有一个中心句。
• 中心句子放在段首，之后的句子都应该是为这句话服务。
• 一个段落最多不要超过7行，最佳段落小于或者等于4行。
• 段落间用空行分割开。
• 段落前不要用空白字符。
• 段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。

引用

每一张图片的下面指明图片的来源。

本文部分图片来自 Wikipedia

数值

---

数值范围

用——或者～连接，有单位和百分号的时候，建议带上单位。

12kg～24kg
12%～24%

变化程度

数值的增加要用“增加了”，“增加到”来表示。

增加到过去的两倍
（过去为一，现在为二）

增加了两倍
（过去为一，现在为三）

标点符号

---

原则

• 中文句子就用全角符号，保持视觉的一致性。
• 英文句子就用半角符号。

句号

句子末尾用括号加注时，句号应在括号之外。

错误：关于文件的输出，请参照第 1.3 节（见第 26 页。）

正确：关于文件的输出，请参照第 1.3 节（见第 26 页）。

顿号

中文句子里，并列的中文单词和英文单词都用、。英文句子里用,。

我喜欢苹果、栗子、西瓜和草莓。
我喜欢 Python、Javascript 和 Java。
I like Python, Javascript and Java.

文档体系

---

结构

参考以下的结构。

• 简介（Introduction）： [必备] [文件] 提供对产品和文档本身的总体的、扼要的说明
• 快速上手（Getting Started）：[可选] [文件] 如何最快速地使用产品
• 入门篇（Basics）： [必备] [目录] 又称”使用篇“，提供初级的使用教程
  • 环境准备（Prerequisite）：[必备] [文件] 软件使用需要满足的前置条件
  • 安装（Installation）：[可选] [文件] 软件的安装方法
  • 设置（Configuration）：[必备] [文件] 软件的设置
• 进阶篇（Advanced)：[可选] [目录] 又称”开发篇“，提供中高级的开发教程
• API（Reference）：[可选] [目录|文件] 软件 API 的逐一介绍
• FAQ：[可选] [文件] 常见问题解答
• 附录（Appendix）：[可选] [目录] 不属于教程本身、但对阅读教程有帮助的内容
  • Glossary：[可选] [文件] 名词解释
  • Recipes：[可选] [文件] 最佳实践
  • Troubleshooting：[可选] [文件] 故障处理
  • ChangeLog：[可选] [文件] 版本说明
  • Feedback：[可选] [文件] 反馈方式

文件名

• 除了特殊的文件：README.md 等，文件名的开头都用小写。
• 文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。
• 文件名包含多个单词时，单词之间建议使用半角的连词线（-）分隔。