2022-03-08 14:21:14 +08:00
---
id: 文档内容
title: 文档内容
sidebar_position: 4
data: 2022年3月8日
---
## 空白符号
空白符号包括空格、空行等，其中空格分为半角空格和全角空格。
### 空白的使用
技术文档中使用空白符号建议遵循以下规范。
| 空白类型 | 相应规范 |
| -------- | ------------------------------------------------------------ |
| 空格 | - 禁止使用全角空格，**一律使用半角空格**。 - 中文字符（包括汉字和中文标点符号）和中文字符之间禁止空半角空格。 - **英文字符和阿拉伯数字**一般使用半角格式， ， ： ） ， ； ） ， （ ）
| 空行 | - 不同段落间建议使用一个空行隔开。 - 不同排版格式之间建议使用一个空行隔开，如标题与紧跟着的正文之间，正文与代码块之间、正文与表格之间等。 - 禁止连续出现两个及以上的空行。 |
| 其他 | 行宽：相同排版格式内保持一致即可，可自由在 80、120 字符中选择，原则上不超过 160 字符宽。 |
### Tab 和空格的使用
技术文档中经常使用 Tab 键和空格键进行缩进和对齐。由于在不同的编辑器里 Tab 的默认长度可能不一致，用 Tab 键设置缩进可能导致格式混乱。如果使用空格键设置缩进，则用任何编辑器打开文档都会显示一样的对齐效果。
因此建议：
- 使用空格键而不用 Tab 键进行缩进或对齐。
- 使用 Tab 键缩进是可以接受的，但**禁止混用 Tab 和空格**进行缩进。
- 在 Visual Studio Code 等编辑器里统一设置一个 Tab 等于四个半角空格。
## 列表
当有 3 项或更多重要信息需要展示时，纵向列表是最清晰且吸引眼球的方式。但如果项目少于 3 项且无需特别强调，将其直接放在句子中通常效果更好。
也可以创建多级嵌套列表，在某一级别下另起一行，缩进**四个空格**即可开始更低级别的列表。
### 无序列表和有序列表
技术文档中的列表分为有序列表 (ordered list) 和无序列表 (unordered list) 两种。一般而言，**当列表项之间的顺序不重要时，使用无序列表；当各项之间的顺序很重要时，使用有序列表。**
【无序列表示例】
目前，
- Prometheus Server：
- Client 代码库：用于定制程序中需要的 Metric。
- Alertmanager：
【有序列表示例】
解决办法：
1. 编辑数据源文件。
2. 手动创建所有的表。
3. 设置参数跳过检查。
有序列表的使用场景较少。当列表项的内容是以下几种时，应该使用有序列表。
- 必须按顺序操作的步骤（最常用）
- 需要进行排名的多项内容
- 需要在下文进行引用的规则或其它信息（比如下文需要引用该列表的第 3 项时可以说“规则 3”）
**【重要原则】除非顺序很重要，否则不建议使用有序列表。**
### 列表的使用
技术文档中使用列表建议遵循以下规范。
| 使用列表的规范 | 错误案例 | 正确案例 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 1. 并列列表项中建议使用相似的句子结构。 | SQL 查询优化器： - 支持 eager aggregate - 更详细的 explain 信息 - union 算子并行化 - 子查询性能优化 - 优化 CBO 框架 | SQL 查询优化器： - 支持 eager aggregate - 支持更详细的 explain 信息 - 支持 union 算子并行化 - 优化了子查询性能 - 优化了 CBO 框架 |
| 2. 每一项的长度要尽量接近。 | 在 GitHub 上提交的新 Issue 分为以下几种： - 如果您发现了 bug 需要报告 - 请求开发一项新功能 - 常规问题 - 为解决或提升性能提的 Issue | 在 GitHub 上提交的新 Issue 分为以下几种： - 错误报告 - 功能请求 - 常规问题 - 性能问题 |
| 3. 避免在每一项开头重复相同的词语。 | TiDB 与 MySQL 安全特性的差异： - 不支持外部身份验证方式。 - 不支持列级别权限设置。 - 不支持使用证书验证身份。 | 相较于 MySQL 安全特性，
| 4. 使用清晰的、描述性的句子或短语来引出列表。 | 状态可以通过 store 的 state_name 来确定： - Up： ： ： ： ： ：
| 5. 并列列表项中保持标点符号一致。 若列表项是句子，那么每一项建议以句号结尾； 若列表项是词组，则不建议以任何标点结尾； 若列表项既有词组又有句子，则建议统一以句号结尾。 | 【例一】TiDB Binlog 支持以下功能场景： - 数据同步。 - 实时备份和恢复。 【例二】指定数据源的相关信息： - 在 Name 处，为数据源指定一个名称。 - 在 Type 处，选择 Prometheus。 - 在 URL 处，指定 Prometheus 的 IP 地址。 - 其他字段 | 【例一】TiDB Binlog 支持以下功能场景： - 数据同步 - 实时备份和恢复 【例二】指定数据源的相关信息： - 在 Name 处，为数据源指定一个名称。 - 在 Type 处，选择 Prometheus。 - 在 URL 处，指定 Prometheus 的 IP 地址。 - 其他字段。 |
| 6. 不要滥用无序列表，否则会导致它们失去应有的效果。 | 无 | 无 |
| 7. 避免嵌套使用列表，这样通常会显得冗长复杂。 如果一定要表现多层级的列表，建议最多不超过 3 级，且每一级都要用不同样式的小圆点。 | 无 | 无 |
| 8. 一个操作任务的步骤描述通常要使用有序列表，为方便用户记忆，建议严格限制列表项在 7 个以下，最多不要超过 9 个步骤。 | 无 | 无 |
## 表格
技术文档中使用表格建议遵循以下规范。
1. 样式规范
- 单元格中的所有内容都**建议保持左对齐**。
- 所有表格都需要有表头描述，即表格第一行中描述各列内容的短语。
- 保证表格同一行的单元格不跨页。
- 每个表格下都要空一行，这一空行的样式为正文。如遇到换页的情况，表格后的空行在新页的第一行，则这行空行必须删除。
2. 表头规范
同一技术文档或产品手册中相同类型表格的表头描述需要保持一致。
【注意】对参数进行说明的表，应该统一表头描述，不要出现“参数说明”、“参数解释”、“参数含义”、“参数意义”等不同的描述。
3. 单元格内容规范
- 表格中的内容应该尽量简练，文字表述风格保持一致。避免长篇大段的说明，建议单元格中的内容所占行数不要超过 6 行。
- 不出现空白的单元格。建议无内容单元格填写“无”或特定含义符号（如“/”）。若使用特定含义符号，需说明符号代表的意义。
- 单元格内容避免重复。如果多个单元格中的内容相同，建议将内容复制或者采用多个单元格合并的方式，不要使用“同上”。
4. 表说明规范
表说明即表格之前或之后的一行表描述，可能带有序号或编号，主要是为了简要描述表格内容。
- 表说明采用名词词组形式。
- 表说明简明扼要，长度不能超过表的宽度。
- 同类表格的表说明在全文中风格保持统一。
## 图形和图片
技术文档中插入图形与图片建议遵循以下规范。
- 必须使用清晰可辨的图形图片。
- 中文文档里图形图片上的文字建议都用中文，如果原图文字是其他语言，应该先做好图片本地化工作。
- 文字建议使用**免费开源可商用字体**，以免引入法律风险。如不确定使用的字体是否能商用，可以在 [360 查字体 ](http://fonts.safe.360.cn/ )网站中查证。
- 同一文档内图形图片上的中文应该统一字体（ ） ， （ ）
- 图形图片中避免出现大段文字，描述性语言建议放到图外，用编号替代。
- 图形图片中包含缩略语时，需要在图说明中对缩略语进行解释。
- 图说明和图尽量保证在同一页中显示。
- 图片的命名建议使用描述性的文字。
- 插入图片时建议添加替代文本， ， `alt` 属性](https://www.w3school.com.cn/html/html_images.asp)， ，
## 注意和说明
注意和说明内容在技术文档中起强调作用。技术文档中使用注意和说明建议遵循以下规范。
- 根据提示内容的级别和分类使用不同的文字描述。例如，分类可以包括“危险”、“警告”、“小心”、“注意”、“说明”、“建议”、“举例”、“错误”等。
- 注意和说明中不能包含表格和图形。
- 注意和说明的内容不能过长，建议不要超过 4 行。
## 代码块和代码注释
技术文档中插入代码块建议遵循以下规范。
- 代码块前后必须加上一行空行。
- 代码块要注意缩进。例如，当前代码块属于列表项下的内容，则要在该列表项的缩进基础上再缩进四格。
- 如果前端支持，建议高亮代码块，方便阅读。
- 如果前端支持，建议为代码块加上可供用户直接复制代码的按钮，提高文档易用性。
代码注释一般出现在多行代码块中。技术文档中插入代码注释建议遵循以下规范。
- 一行注释不能太长，太长时应适当进行断句并切分到下一行。
- 一行注释末尾建议加上标点符号，一般是句号；与下一行的内容承接时，用逗号。
- 必须根据代码块中定义的语法选择相应的注释符，不能自创注释符。
## 链接
技术文档中的链接将用户引导至同一文档中的其他标题、其他相邻文档或外部站点。本节主要介绍在使用 Markdown 语言编写的技术文档中使用链接建议遵循的规范。
Markdown 中的链接格式示例：
- 链至同一文档中的其他标题：`[产品架构](#产品架构)`
2022-04-29 11:28:04 +08:00
- 链至其他相邻文档：`[产品架构](#产品架构)`
2022-03-08 14:21:14 +08:00
- 链至外部站点：`[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/)`
### 链接的描述
Markdown 链接中方括号 `[]` 里的内容为该链接的描述性文本。链接的描述需要符合以下规范。
- 链接描述必须能概括所链文档或页面的大致内容，这有利于搜索引擎优化。例如，链接描述可以是所链页面的标题。
- 【错误示例】
2022-04-29 11:28:04 +08:00
- 详情参见 `[trouble-shooting.md](trouble-shooting)`
- 详情请点击`[这里](trouble-shooting)`
2022-03-08 14:21:14 +08:00
- 【正确示例】
- 关于以上配置项的更多细节，参见`[功能配置集](#功能配置集)`的相关配置项。
2022-04-29 11:28:04 +08:00
- 详情参见`[故障诊断文档](trouble-shooting)`。
2022-03-08 14:21:14 +08:00
- 同类型的链接描述应尽量统一风格。例如：同一文档内不宜多次出现“详情参见”、“详情参阅”、“具体见”、“具体请见”等表达相同意思的不同描述。
### 链接的路径
Markdown 链接中圆括号 `()` 里的内容即为该链接的路径。链接的路径需要符合以下规范。
- **如链至其他相邻文档，且链接的文档篇幅较长，建议链接至锚点**。链接至锚点即链接至某级标题处。Markdown 支持在链接路径的文件名后加“#标题名称”，即可以链接至该文件的特定标题处。
2022-04-29 11:28:04 +08:00
- 【示例】`[配置文件](#配置文件)`这个链接将链至 trouble-shooting.md 文件的“配置文件”标题下。
2022-03-08 14:21:14 +08:00
- 链接路径应尽量统一风格。例如，链接至非外部站点时应统一使用相对路径或绝对路径，不建议混用相对路径和绝对路径。
- 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验。
> 外部站点的含义： ， ： ；
- **如果必须将用户链至外部站点，建议在该外链后加上明显的标示，提醒用户该链接将前往外部站点。**
> 由于不同网站的使用条款和隐私政策不同，用户使用当前站点，一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前，网站维护者有责任提醒用户当前的链接是去往外部站点，跳出去之后如果用户发生问题，不是当前站点的责任。
- 【示例一】如果前端能力足够，可以在外链后加上通用的外链 icon 效果，比如：[贡献者名单](https://github.com/yikeke/zh-style-guide/graphs/contributors)。
- 【示例二】在 Markdown 中，可以简单在链接的路径后加上 `"点击前往外部站点"` 或者 `"点击前往 XXX 网站"` 等信息，如 `[链接的描述](链接的路径 "前往外部链接的提示")` ，即可在正常渲染下，实现鼠标悬停在超链接上时出现提示的效果。
## 引用
技术文档中使用引用建议遵循以下规范。
- 当某内容在其他地方已经详细描述过、不适合在正文中再次介绍时，可以使用引用。
- 对于必须引用但内容很少（少于 100 字）的情况，建议直接在该处重新描述一遍。
- 必须保证引用的位置准确。
技术文档中引用第三方内容建议遵循以下规范。
- 引用他人的语句时，应注明出处。
- 【示例】One man’ ’
- 全篇转载时，应在全文开头显著位置注明作者和出处，并链接至原文。
- 【示例】本文转载自 WikiQuote
- 使用外部图片时，必须在图片下方或文末标明来源。
- 【示例】本文部分图片来自 Wikipedia
## 缩略语
中文技术文档中的缩略语有两种：汉语缩略语和英语缩略语。下文分别介绍了两者的概念、特点及使用规范。
### 汉语缩略语
汉语缩略语是由较长的中文语词缩短省略而成的语词，如“人大”、“重启”、“停机”、“绑核”等。
由于汉语缩略语一般数量较少、含义明确，在技术文档中只要保证该缩略语通俗易懂、不造成歧义，原则上不限制使用次数。如果某词在文档中必须大量使用，但其缩略语不常见，建议在该词第一次出现时说明情况，提示读者下文中将以缩略语的形式称呼该词。
### 英语缩略语
英语缩略语数量巨大、种类繁多，出现在中文技术文档中的主要有三种：首字母缩略词 (acronym)、字母词 (initialism) 和缩写词 (shortened word) 。三者的区别是：
- 首字母缩略词：由每个词的首字母组成，以词的形式发音。
- 【示例】NATO 代表 North Atlantic Treaty Organization
- 字母词：也是由每个词的首字母组成，但按字母逐字发音。
- 【示例】FBI 代表 Federal Bureau of Investigation
- 缩写词：由较长的中文语词缩短省略而成的语词。
- 【示例】App 代表 Application；
在技术文档中使用英语缩略语建议遵循以下规范。
- 不建议在标题中解释英文缩略语，以免造成标题冗长。
- 建议在正文中第一次出现缩略语的地方解释其完整含义。
- 某词用缩略语进行代称时，必须在该词第一次出现时说明情况，提示读者下文中将以缩略语的形式称呼该词。
- 禁止使用不规范的缩略语， ， ；
## 数字
在中文语境中， ： ， ； ，
技术文档中汉字数字和阿拉伯数字的用法建议遵循以下规范。
### 数字形式的选用
除一些惯用场景和特殊场景外，如果希望达到**突出强调、易于辨识**的效果，应采用阿拉伯数字；如果希望突出**正式、庄重**的表达效果，应使用汉字数字。
#### 选用阿拉伯数字
| 适用场景 | 示例 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| 用于计量（即用于加、减、乘、除等数学运算）的数字，如正负整数、小数、百分比、比例、分数等。 | -126、34.05%、63%～
| 当数值伴随有计量单位，如长度、容积、面积、体积、质量、温度、经纬度、音量、频率等，特别是当计量单位以字母表达时 | 524.5 km（ ） （ ） （
| 用于编号的数字 | - 电话号码： ： ： ： ： ： ： ： ： ：
| 现代社会生活中出现的事物、现象、事件，其名称的书写形式中包含阿拉伯数字，已经广泛使用而稳定下来 | 4G 手机、MP4 播放器、维生素 B12、“5·27”事件 |
| 希望突出简洁醒目的表达效果时 | 北京时间 2020 年 10 月 1 日 12 点整 |
#### 选用汉字数字
| 适用场景 | 示例 |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| 数字连用表示的概数、含“几”的概数等 | 三四个月、一二十个、十五六岁、五六万套、五六十年前、几千、二十几、一百几十、几十万分之一 |
| 干支纪年、农历月日、历史朝代纪年及其他传统上采用汉字形式的非公历纪年 | 腊月二十三、正月初五、八月十五中秋、秦文公四十四年、太平天国庚申十年九月二十三号、日本庆应三年、丙寅年十月十五日 |
| 汉语中长期使用且已稳定下来的包含汉字数字形式的词语 | 星期五、四氧化三铁、一方面、不二法门、二八年华、二百五、八国联军、五四运动、万一、一旦、四书五经、七上八下、不管三七二十一、半斤八两、“一·二八”事变、“一·二九”运动 |
| 希望突出庄重典雅的表达效果时 | 六方会谈（ ） （
#### 选用阿拉伯数字和汉字数字均可
如果表达计量或编号所需要用到的数字个数不多，选择阿拉伯数字还是汉字数字在书写的简洁性及辨识的清晰性两方面没有明显差异时，两种形式均可使用。
如下表所示，在不同场景下，下列两种形式均可使用：
| 阿拉伯数字形式 | 汉字数字形式 |
| ----------------- | -------------------- |
| 3 倍 | 三倍 |
| 100 多个数据中心 | 一百多个数据中心 |
| 20 余次 | 二十余次 |
| 约 300 人 | 约三百人 |
| 40 左右 | 四十左右 |
| 第 40 页 | 第四十页 |
| 第 9 天 | 第九天 |
| 第 4 季度 | 第四季度 |
| 共 128 位贡献者 | 共一百二十八位贡献者 |
| 0.5 | 零点五 |
| 1/3 | 三分之一 |
| 公元前 8 世纪 | 公元前八世纪 |
| 20 世纪 80 年代 | 二十世纪八十年代 |
| 公元 278 年 | 公元二七八年 |
| 1997 年 4 月 1 日 | 一九九七年四月一日 |
| 下午 4 点 27 分 | 下午四点二十七分 |
#### 其他注意事项
1. 在同一场景出现的数字，应遵循“同类别同形式”原则来选择数字的形式。
如果两个数字的表达功能类别相同（比如都是表达年月日时间的数字），或者两个数字在上下文中所处的层级相同（比如文章目录中同级标题的编号），应选用相同的数字形式。反之，如果两个数字的表达功能不同，或所处层级不同，可以选用不同的形式。
- 【示例一】2020 年 10 月 1 日 或者 二〇二〇年十月一日 （不写为“二〇二〇年 10 月 1 日”）
- 【示例二】第一章 第二章……第十二章（不写为“第一章 第二章……第 12 章”）
- 【示例三】第二章的下一级标题可以用阿拉伯数字编号：
2. 应避免相邻的两个阿拉伯数字造成歧义的情况。
- 【示例一】高三三个班 或者 高三 3 个班（不写为“高 3 3 个班”）
- 【示例二】高三 2 班 或者 高三 (2) 班（不写为“高 3 2 班”）
3. 有法律效力的文件、公告文件或财务文件中可同时采用汉字数字和阿拉伯数字。
- 【示例一】2019 年 7 月保险账户结算日利率为万分之一点五七五零 (0.015750%)
- 【示例二】35.5 元（
### 阿拉伯数字的使用
技术文档中使用阿拉伯数字建议遵循如下规范。
#### 格式
书写格式上建议遵循如下字体、空格、换行规范。
- 数字与英文字母一样，一律使用**半角形式**（即半个汉字位置），不得使用全角形式。
- 【错误示例】每２分钟导入一个２５６ MB 的数据文件。
- 【正确示例】每 2 分钟导入一个 256 MB 的数据文件。
- 在不作任何后期排版处理的前提下，建议半角数字两旁各空一个空格。
- 【错误示例】每2分钟导入一个256MB 的数据文件。
- 【正确示例】每 2 分钟导入一个 256 MB 的数据文件。
- 一个用阿拉伯数字书写的数值必须在同一行中，**不能断开移行**。
#### 多位数值
技术文档中书写多位数值建议遵循如下规范。
- 数值巨大的精确数字， ，
- 数值为千位以上，建议添加半角逗号“,”作为分节符。
- 多位整数从右到左分节，每三位一节，如 2,345,567,456。
- 小数部分不分节，如 19,256,289.23456。
- 四位以内的整数可以不分节，如 1289。
#### 数值范围
技术文档中书写数值范围建议遵循如下规范。
- 在表示数值的范围时，可采用浪纹式连接号“～”或一字线连接号“—”。
【示例】-36～ ～
- 前后两个数值的附加符号或计量单位相同时，在**不造成歧义**的情况下，前一个数值的附加符号或计量单位可省略。
【示例】9 亿～ ～ ） ～ ～ ） ～ （ ～ ） ～ ～ ）
#### 年月日
技术文档中使用阿拉伯数字表示年月日，建议遵循如下规范。
- 四位数字表示的年份不应简写为两位数字。如“2019 年”不应简写为“19 年”。
- 年月日的表达顺序按照口语中年月日的自然顺序书写。如 2008 年 8 月 8 日、1997 年 4 月 1 日。
- “年”“月”可用“-”替代，但年月日不完整时不能替代。如 2020-8-8、1997-4-1、8 月 8 日（ ） （ ）
- 月和日为一位数时，
#### 时分秒
技术文档中使用阿拉伯数字表示时分秒，建议遵循如下规范。
- 计时方式既可采用 12 小时制，也可采用 24 小时制。如 11 时 31 分 或者 21 时 12 分。
- 时分秒的表达顺序按照口语中时、分、秒的自然顺序书写。如 15 时 31 分、14 时 12 分 36 秒。
- 时分秒也可使用“:”替代。如 14:12:16、3:15:59。
#### 含有月日的专名
含有月日的专名采用阿拉伯数字表示时，应采用间隔号“·”将月、日分开，并在数字前后加引号，避免歧义。
【示例】“3·15”消费者权益日。
### 汉字数字的使用
技术文档中使用汉字数字建议遵循如下规范。
#### 概数
两个数字连用表示概数时，建议两数之间不用顿号“、”隔开。
【示例】二三米、一两个小时、三五天、五六十年代、四五十岁
#### 年份
年份简写后的数字可以理解为概数时，一般不简写。
【示例】“一九七八年”不写为“七八年”
#### 含有月日的专名
含有月日的专名采用汉字数字表示时，如果涉及一月、十一月、十二月，应用间隔号“·”将表示月和日的数字分开，并在数字前后加引号，避免歧义。涉及其他月份时，不用间隔号。
【示例】“一·二八”事变、“一二·九”运动、五一国际劳动节
#### 大写汉字数字
汉字数字有大写形式，分别是：零（或“〇”）、壹、贰、叁、肆、伍、陆、柒、捌、玖、拾、佰、仟、万和亿。
大写汉字数字的使用场景：法律文书和财务票据上，应采用大写汉字数字记数。
【示例】3,504 元（叁仟伍佰零肆圆）
#### “零”和“〇”
阿拉伯数字 0 有“零”和“〇”两种汉字书写形式。一个数字用于计量时，建议用“零”；用于编号时，建议用“〇”。
【示例】
- “2052”的汉字形式为“两千零五十二”（ 〇 ）
- “100.06”的汉字形式为“一百点零六”（不写为“一百点〇六”）
- “公元 2019 年”的汉字形式为“二〇一九”（不写为“二零一九”）
#### 二、2、两的用法
> 以下规范来源于[《常见语言文字错误防范手册》](https://baike.baidu.com/item/常见语言文字错误防范手册)。
“二”“2”“两”表示的数值相同， ：
- “二”“两”在度量衡单位和百千万前面可以通用。
- 序数、分数、小数用“二”，不用“两”。
- 常用量词（如个、本、件、回、种、天）前面，用“两”不用“二”。
- 用“二”和“两”的地方如果强调计量和统计意义时可以用“2”。
## 单位符号
技术文档中使用单位符号建议遵循以下规范。
- 为避免指代不明，**建议用汉字名称代替单位符号**，如毫米代替 mm、小时代替 h、分钟代替 min。
- **大多数情况下，数值与单位符号之间需要空一个半角空格**，如 7 kg、8 MB、10 GB。但有几种例外：
- 单位是角度、摄氏度或百分号时， ：
- 单位是英尺符号和英寸符号时， ： ′ `′ （ `″` （
