技术文档写作规范
标题#
（1）一级标题下，不能直接出现三级标题。
示例：下面的文章结构，缺少二级标题。
# 一级标题
### 三级标题（2）标题要避免孤立编号（即同级标题只有一个）。
示例：下面的文章结构，二级标题 A只包含一个三级标题，完全可以省略三级标题 A。
## 二级标题 A
### 三级标题 A
## 二级标题 B（3）谨慎使用四级标题，尽量避免出现，保持层级的简单，防止出现过于复杂的章节。
如果三级标题下有并列性的内容，建议只使用项目列表（Item list）。
示例：下面的结构二要好于结构一。后者适用的场景，主要是较长篇幅的内容。
结构一
### 三级标题
#### 四级标题 A
#### 四级标题 B
#### 四级标题 C
结构二（**建议使用**）
### 三级标题
**（1）A**
**（2）B**
**（3）C**空格#
中文与数字之间#
全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。
正确：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。
正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。半角的百分号，视同阿拉伯数字。（**建议使用**）数字与英文单位之间#
英文单位若不翻译，单位前的阿拉伯数字与单位间不留空格。
正确：一部容量为 16GB 的智能手机
错误：一部容量为 16 GB 的智能手机文本#
句子#
- 避免使用长句。句子内部不使用逗号时，总长度不应该超过 40 个字；使用逗号时，总长度不应该超过 100 字或者正文的 3 行。
- 尽量使用简单句和并列句，避免使用复合句。
写作风格#
1、尽量不使用被动语态，改为使用主动语态。
错误：假如此软件尚未被安装，
正确：假如尚未安装这个软件，2、用对“的”、“地”、“得”。
她露出了开心的笑容。（形容词＋的＋名词）
她开心地笑了。（副词＋地＋动词）
她笑得很开心。（动词＋得＋副词）3、使用代词时（比如“其”、“该”、“此”、“这”等词），必须明确指代的内容，保证只有一个含义。
错误：从管理系统可以监视中继系统和受其直接控制的分配系统。
正确：从管理系统可以监视两个系统：中继系统和受中继系统直接控制的分配系统。4、不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，在任何情况下都不能接受。
错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。
正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。5、同样一个意思，尽量使用肯定句表达，不使用否定句表达。
错误：请确认没有接通装置的电源。
正确：请确认装置的电源已关闭。6、避免使用双重否定句。
错误：没有删除权限的用户，不能删除此文件。
正确：用户必须拥有删除权限，才能删除此文件。英文处理#
英文原文如果使用了复数形式，翻译成中文时，应该将其还原为单数形式。
英文：⋯information stored in random access memory (RAMs)⋯
中文：……存储在随机存取存储器（RAM）里的信息……外文缩写可以使用半角圆点(.)表示缩写。
U.S.A.Apple, Inc.英文书名或电影名改用中文表达时，双引号应改为书名号。
英文：He published an article entitled "The Future of the Aviation".
中文：他发表了一篇名为《航空业的未来》的文章。第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。
IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用“IOC”了。专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。
“American Association of Physicists in Medicine”（美国医学物理学家协会）是专有名词，需要大写。
“online transaction processing”（在线事务处理）不是专有名词，不应大写。段落#
原则#
一个段落只能有一个主题，或一个中心句子。
段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。
一个段落的长度不能超过七行，最佳段落长度小于等于四行。
段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。
段落之间使用一个空行隔开。
段落开头不要留出空白字符。
引用#
引用第三方内容时，应注明出处。
One man’s constant is another man’s variable. — Alan Perlis如果是全篇转载，请在全文开头显著位置注明作者和出处，并链接至原文。
本文转载自 WikiQuote使用外部图片时，必须在图片下方或文末标明来源。
本文部分图片来自 Wikipedia数值#
千分号#
数值为千位以上，应添加千分号（半角逗号）。
XXX 公司的实收资本为 RMB1,258,000。对于 4 ～ 6 位的数值，千分号是选用的，比如 1000 和 1,000 都可以接受。对于 7 位及以上的数值，千分号是必须的。
多位小数要从小数点后从左向右添加千分号，比如 4.234,345。货币#
货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。
$1,0001,000 美元4.4 数值范围表示数值范围时，用～连接。参见《标点符号》一节「连接号」部分。
带有单位或百分号时，两个数字都要加上单位或百分号，不能只加后面一个。
错误：132～234kg正确：132kg～234kg
错误：67～89%正确：67%～89%变化程度的表示法#
数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。
增加到过去的两倍（过去为一，现在为二）
增加了两倍（过去为一，现在为三）数字的减少要使用「降低了」、「降低到」。「了」表示增量，「到」表示定量。
降低到百分之八十（定额是一百，现在是八十）
降低了百分之八十（原来是一百，现在是二十）不能用「降低N倍」或「减少N倍」的表示法，要用「降低百分之几」或「减少百分之几」。因为减少（或降低）一倍表示数值原来为一百，现在等于零。
标点符号#
只有中文或中英文混排中，一律使用中文全角符号。例如：
正确：我常用的电子设备是 Kindle、iPad Pro、iPhone。错误：我常用的电子设备是 Kindle, iPad Pro, iPhone.如果引用一段完整的英文句子，或是出现在专有名词中的标点，则在这句英文中使用英文半角标点。例如：
正确：乔布斯说「Stay hungry,Stay foolish.」错误：乔布斯说「Stay hungry，Stay foolish。」
正确：我最喜欢的手机游戏是 Lifeline:Silent Night。错误：我最喜欢的手机游戏是 Lifeline：Silent Night。顿号#
句子内部的并列词，应该用全角顿号(、) 分隔，而不用逗号，即使并列词是英语也是如此。
错误：我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。
正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。英文句子中，并列词语之间使用半角逗号（,）分隔。
例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.感叹号#
应该使用平静的语气叙述，尽量避免使用感叹号！。
不得多个感叹号连用，比如！！和!!!。
连接号#
连接号用于连接两个类似的词。
以下场合应该使用直线连接号（-），占一个半角字符的位置。
- 两个名词的复合
- 图表编号
例句：氧化-还原反应
例句：图 1-1以下场合应该使用波浪连接号（～），占一个全角字符的位置。
- 数值范围（例如日期、时间或数字）
例句：2009 年～2011 年注意，波浪连接号前后两个值都应该加上单位。
波浪连接号也可以用汉字“至”代替。
例句：周围温度：-20°C 至 -10°C省略号#
省略号请使用 …… 标准用法，正确输入方法是 shift + 6。不要使用三个句号。。。，也不要使用三个英文句点 ...。
文档体系#
结构#
软件手册是一部完整的书，建议采用下面的结构。
- 简介（Introduction）： [必备][文件] 提供对产品和文档本身的总体的、扼要的说明
- 快速上手（Getting Started）：[可选][文件] 如何最快速地使用产品
- 入门篇（Basics）： [必备][目录] 又称”使用篇“，提供初级的使用教程
- 环境准备（Prerequisite）：[必备][文件] 软件使用需要满足的前置条件
- 安装（Installation）：[可选][文件] 软件的安装方法
- 设置（Configuration）：[必备][文件] 软件的设置
- 进阶篇（Advanced)：[可选][目录] 又称”开发篇“，提供中高级的开发教程
- API（Reference）：[可选][目录|文件] 软件 API 的逐一介绍
- FAQ：[可选][文件] 常见问题解答
- 附录（Appendix）：[可选][目录] 不属于教程本身、但对阅读教程有帮助的内容
- Glossary：[可选][文件] 名词解释
- Recipes：[可选][文件] 最佳实践
- Troubleshooting：[可选][文件] 故障处理
- ChangeLog：[可选][文件] 版本说明
- Feedback：[可选][文件] 反馈方式
下面是两个真实范例，可参考。
文件名#
文档的文件名不得含有空格。
文件名必须使用半角字符，不得使用全角字符。这也意味着，中文不能用于文件名。
错误： 名词解释.md
正确： glossary.md文件名建议只使用小写字母，不使用大写字母。
错误：TroubleShooting.md
正确：troubleshooting.md 为了醒目，某些说明文件的文件名，可以使用大写字母，比如 README、LICENSE。
文件名包含多个单词时，单词之间建议使用半角的连词线（-）分隔。
不佳：advanced_usage.md
正确：advanced-usage.md注明引用来源#
文中有使用外站或外部内容的，务必在引用最后部分注明来源。
文中有使用外站图片，必须在文末标明。来源如果来自外站必须添加链接。例如，
本文部分图片来自 [The Verge](https://www.theverge.com/)
题图来自电影《春娇与志明》截图- 若文章为全文翻译，必须在文中注明原作者及原文地址，并添加原文链接。