如何写好技术文档 - 排版格式和规范(一)

本文参考谷歌开发文档风格指南、Vue官方文档、React官方文档、掘金小册和阮一峰《中文技术文档的写作规范》，其中排版格式，主要参照Vue、React官网，写作规范部分主要参考阮一峰老师的《中文技术文档的写作规范》。

编写技术文档除了排版格式和规范，思路和风格也极为重要，目前一些亲和、幽默的写作风格往往能获得更多的阅读量。

本文主要分为以下部分展开：

• 排版格式和规范
• 写作思路
• 写作风格

技术文档通常使用markdown编写，所以后面的内容都是针对Markdown文档进行排版。

同时排版格式和写作规范有很多重合部分，所以放在一篇文章说明。

文档结构

以Vue、React官网为例，通常包含下面的文档结构，如果要写一个开源软件的官方文档，可以参考：

1. 开始：包含简介和快速上手
2. 基础：应用基础使用
3. 深入：进阶说明
4. API：API文档
5. FAQ：常见问题解答
6. 参考：参考连接

标题

一篇文章主题应专一，如果出现多个主题，编写多篇文章是更好的选择，主题专一之后，对应的标题才会简洁明了。

应避免标题层级过多，尽量少使用 3 级标题，最好不使用 4 级标题。

标题通常分为 4 级：

• 一级标题：通常不写在文章内部，而是作为文章的标题显示在固定的标题位置。
• 二级标题：文章内部主要使用的标题，类似Vue、React官方文档中，绝大多数文章内只使用了二级标题。
• 三级标题：二级标题下的细分标题，一般在长文章中使用，中短篇文章如果标题设置合理，不需要使用。
• 四级标题：三级标题下的细分标题，不推荐使用，如果书写文章时发现需要使用到四级标题，应查看你的每个二级标题是否属于不同的主题，能否拆分为多篇文章。

下面是标题使用规范：

1.标题下应进行一些必要性简述，不应该直接多层标题重叠。

示例：下面的一、二、三级标题直接放在一起。

结构一

# 一级标题

## 二级标题

### 三级标题

结构二

# 一级标题

这是一级标题的相关描述，可以是简述下面二级大概包括的内容。

## 二级标题

这是二级标题的相关描述。

### 三级标题

2.一级标题下，不能直接出现三级标题，不要跨级使用标题。

示例：下面的文章结构，缺少二级标题。

# 一级标题

### 三级标题

3.标题要避免孤立编号（即同级标题只有一个）。

示例：下面的文章结构，二级标题 A只包含一个三级标题，完全可以省略三级标题 A。

## 二级标题 A

### 三级标题 A

## 二级标题 B

4.下级标题不重复上一级标题的名字。

示例：下面的文章结构，二级标题与下属的三级标题同名，建议避免。

## 概述

### 概述

5.尽量少使用三级标题，不推荐使用四级标题，保持层级的简单，防止出现过于复杂的章节。

如果三级标题下有并列性的内容，建议只使用项目列表来呈现。

示例：下面的结构二要好于结构一。结构一适用的场景，主要是较长篇幅的内容。

结构一

### 三级标题

#### 四级标题 A

#### 四级标题 B

结构二

### 三级标题

1. 四级标题A

2.四级标题B

正文

正文内包括句子、段落、图片和列表等信息，推荐在这些内容之间使用换行，来达到更好的阅读效果。

标点符号

标点符号通用使用规范：

1. 中文语句的标点符号，均应该采取全角符号，这样可以与全角文字保持视觉的一致。
2. 如果整句为英文，则该句使用英文/半角标点。
3. 句号、问号、叹号、逗号、顿号、分号和冒号不得出现在一行之首。
4. 点号（句号、逗号、顿号、分号、冒号）不得出现在标题的末尾，而标号（引号、括号、破折号、省略号、书名号、着重号、间隔号、叹号、问号）可以。

1.句号使用规范

（1）中文语句的结尾处应该用全角句号（。）。

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

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

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

2.逗号使用规范

（1）逗号（，）表示句子内部的一般性停顿。

注意避免"一逗到底"，即整个段落除了结尾，全部停顿都使用逗号。

3.顿号使用规范

（1）句子内部的并列词，应该用全角顿号(、) 分隔，而不用逗号，即使并列词是英语也是如此。

错误：我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。

正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。

（2）英文句子中，并列词语之间使用半角逗号（,）分隔。

例句：Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.

中文句子内部的并列词，最后一个尽量使用（和）来连接，使句子读起来更加连贯，下面两个句子都可以，第二个更优。

正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里，以及百度等。

正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。

4.分号使用规范

（1）分号（；）表示复句内部并列分句之间的停顿。

5.引号使用规范

引用时，应该使用全角双引号（" "），注意前后双引号不同。

例句：许多人都认为客户服务的核心是"友好"和"专业"。

（2）引号里面还要用引号时，外面一层用双引号，里面一层用单引号（' '），注意前后单引号不同。

例句：鲍勃解释道："我要放音乐，可萨利说，'不行！'。"

6.括号使用规范

（1）补充说明时，使用全角圆括号（（）），括号前后不加空格。

例句：请确认所有的连接（电缆和接插件）均安装牢固。

几种括号的中英文名称。

	英文	中文
{ }	braces 或 curly brackets	大括号
[ ]	square brackets 或 brackets	方括号
< >	angled brackets	尖括号
( )	parentheses	圆括号

7.冒号使用规范

（1）全角冒号（：）常用在需要解释的词语后边，引出解释和说明。

例句：请确认以下几项内容：时间、地点、活动名称和来宾数量。

（2）表示时间时，应使用半角冒号（:）。

例句：早上 8:00

8.省略号使用规范

（1）省略号（⋯⋯）表示语句未完、或者语气的不连续。

（2）省略号占两个汉字空间、包含六个省略点，不要使用。。。或...等非标准形式。

（3）省略号不应与"等"这个词一起使用。

错误：我们为会餐准备了香蕉、苹果、梨...等各色水果。

正确：我们为会餐准备了各色水果，有香蕉、苹果、梨⋯⋯

正确：我们为会餐准备了香蕉、苹果、梨等各色水果。

9.感叹号使用规范

（1）应该使用平静的语气叙述，尽量避免使用感叹号（！）。

（2）不得多个感叹号连用，比如！！和!!!。

10.破折号使用规范

（1）破折号------------一般用于进一步解释。

（2）破折号应占两个汉字的位置。如果破折号本身只占一个汉字的位置，那么前后应该留出一个半角空格。

例句：直觉------------尽管它并不总是可靠的------------告诉我，这事可能出了些问题。

例句：直觉 ------ 尽管它并不总是可靠的 ------ 告诉我，这事可能出了些问题。

11.连接号使用规范

（1）连接号用于连接两个类似的词。

（2）以下场合应该使用直线连接号（-），占一个半角字符的位置。

• 两个名词的复合

• 图表编号

  例句：氧化-还原反应

  例句：图 1-1

（3）数值范围（例如日期、时间或数字）应该使用波浪连接号（～）或一字号（---），占一个全角字符的位置。

例句：2009 年～2011 年

注意，波浪连接号前后两个值都建议加上单位。

（4）波浪连接号也可以用汉字"至"代替。

例句：周围温度：-20 °C 至 -10 °C

文本

markdown中文本排版直接从最左侧开始即可，不用空两个字。

下面是文本的使用规范：

1.少量使用文本加粗。

一定是非常重要的内容才使用加粗，随意使用将导致整个文章显示效果不佳，同时重点内容也不明显。

2.全角中文字符与半角英文字符之间，应有一个半角空格。

错误：本文介绍如何快速启动Windows系统。

正确：本文介绍如何快速启动 Windows 系统。

3.全角中文字符与半角阿拉伯数字之间，有没有半角空格都可，但必须保证风格统一，不能两种风格混杂。

正确：2011年5月15日，我订购了5台笔记本电脑与10台平板电脑。

正确：2011 年 5 月 15 日，我订购了 5 台笔记本电脑与 10 台平板电脑。

半角的百分号，视同阿拉伯数字。

正确：今年我国经济增长率是6.5%。

正确：今年我国经济增长率是 6.5%。

4.英文单位若不翻译，单位前的阿拉伯数字与单位符号之间，应留出适当的空隙。

例1：一部容量为 16 GB 的智能手机

例2：1 h = 60 min = 3,600 s

5.半角英文字符和半角阿拉伯数字，与全角标点符号之间不留空格。

错误：他的电脑是 MacBook Air 。

正确：他的电脑是 MacBook Air。

数值

1.阿拉伯数字一律使用半角形式，不得使用全角形式。

错误：这件商品的价格是１０００元。

正确：这件商品的价格是 1000 元。

2.数值为千位以上，应添加千分号（半角逗号）。

XXX 公司的实收资本为 ￥1,258,000 人民币。

对于 4 位的数值，千分号是选用的，比如1000和1,000都可以接受。对于 4 位以上的数值，应添加千分号。

3.货币应为阿拉伯数字，并在数字前写出货币符号，或在数字后写出货币中文名称。

$1,000
1,000 美元

4.表示数值范围时，用波浪线（～）或一字线（---）连接。参见《标点符号》一节的"连接号"部分。

带有单位或百分号时，两个数字建议都要加上单位或百分号。

132 kg～234 kg

67%～89%

5.数字的增加要使用"增加了"、"增加到"。"了"表示增量，"到"表示定量。

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

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

6.数字的减少要使用"降低了"、"降低到"。"了"表示增量，"到"表示定量。

降低到百分之八十
（定额是一百，现在是八十）

降低了百分之八十
（原来是一百，现在是二十）

不能用"降低 N 倍"或"减少 N 倍"的表示法，要用"降低百分之几"或"减少百分之几"。因为减少（或降低）一倍表示数值原来为一百，现在等于零。

句子

句子使用规范：

1.避免使用长句。

不包含任何标点符号的单个句子，或者以逗号分隔的句子构件，长度尽量保持在 20 个字以内；20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。

错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。

正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

逗号分割的长句，总长度不应该超过 100 字或者正文的 3 行。

2.尽量使用简单句和并列句，避免使用复合句。

并列句：他昨天生病了，没有参加会议。

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

3.同样一个意思，尽量使用肯定句表达，不使用否定句表达。

错误：请确认没有接通装置的电源。

正确：请确认装置的电源已关闭。

4.避免使用双重否定句。

错误：没有删除权限的用户，不能删除此文件。

正确：用户必须拥有删除权限，才能删除此文件。

下面再看看英文的处理规范：

1.英文原文如果使用了复数形式，翻译成中文时，应该将其还原为单数形式。

英文：...information stored in random access memory (RAMs)...

中文：⋯⋯存储在随机存取存储器（RAM）里的信息⋯⋯

2.外文缩写可以使用半角圆点(.)表示缩写。

U.S.A.
Apple, Inc.

3.表示中文时，英文省略号（...）应改为中文省略号（⋯⋯）。

英文：5 minutes later...

中文：5 分钟过去了⋯⋯

4.英文书名或电影名改用中文表达时，双引号应改为书名号。

英文：He published an article entitled "The Future of the Aviation".

中文：他发表了一篇名为《航空业的未来》的文章。

5.第一次出现英文词汇时，在括号中给出中文标注。此后再次出现时，直接使用英文缩写即可。

IOC（International Olympic Committee，国际奥林匹克委员会）。这样定义后，便可以直接使用"IOC"了。

6.专有名词中每个词第一个字母均应大写，非专有名词则不需要大写。

"American Association of Physicists in Medicine"（美国医学物理学家协会）是专有名词，需要大写。

"online transaction processing"（在线事务处理）不是专有名词，不应大写。

段落

下面是段落的写作规范：

• 一个段落只能有一个主题，或一个中心句子。
• 段落的中心句子放在段首，对全段内容进行概述。后面陈述的句子为中心句子服务。
• 一个段落的长度不能超过七行，最佳段落长度小于等于四行。
• 段落的句子语气要使用陈述和肯定语气，避免使用感叹语气。
• 段落之间使用一个空行隔开。
• 段落开头不要留出空白字符。

列表

列表包含无序列表和有序列表，推荐使用下面的规范：

1.必须是并列和递进关系的内容，才使用列表。

绝大多数内容其实并不需要使用列表，查看React官方文档，知识点基本使用了大量的正文进行描述，其中并没有用小标题和列表进行分隔。

除非内容存在并列和递进关系，并且仅仅是简单罗列，才考虑使用列表，以Vue官方文档为例，API文档中，一个对象包含多个函数和属性，它们是并列关系，但并不需要采用列表来表示，使用标题分隔是更佳的选择。

当确定要使用列表时，注意并列关系时使用无序列表，递进关系使用有序列表。

2.列表之间不要添加内容，紧密结合在一起展示。

列表应该尽可能直观的排列在一起，如果列表之前需要添加内容，那么应该考虑将列表项换成标题。

本文前面内容就是一个反例，列表项之间添加了列表的一些描述，主要原因是本文是一个汇总式文章，每个列表项之间仅是简单叙述，如果存在大量描述的话，应该使用标题来代替列表项名。

其它markdown内容

引用

因为markdown拥有的格式种类还是比较有限，所以引用标签除了引用第三方内容外，通常还可以用于显示一些提示、警告、总结等信息。

Vue和React官方不是单纯的markdown格式，所以可以使用更丰富的css来显示这部分内容。

如：

提示

这里是提示内容，和上面的提示最好隔一行。

下面是引用第三方内容时使用规范：

1.引用第三方内容时，应注明出处。

One man's constant is another man's variable. --- Alan Perlis

2.如果是全篇转载，请在全文开头显著位置注明作者和出处，并链接至原文。

本文转载自 WikiQuote

3.使用外部图片时，必须在图片下方或文末标明来源。

本文部分图片来自 Wikipedia

代码

代码包含句子中提及的关键词代码和大段的演示代码。

1.句子中提及的代码，应尽量少用代码标签包裹。

一个句子中可能提及很多代码关键词，但是只用 code 标签包裹当前上下文关注的代码关键词是更好的选择，高亮过多代码关键词整个句子看起来会杂乱。

2.代码块应尽量选择正确的代码语言，以高亮正确的关键字。