wiki/Tech/software-engineering/技术文档/5.文档内容.md

---
title: 文档内容
description: 本文提供了技术文档编写的详细规范，包括正确使用空白符号、列表、表格、图形图片、代码块及注释、链接和引用，以及缩略语和数字表达方式。强调了文档的清晰性、准确性和易读性，同时指出了常见的错误用法。
keywords:
  - 技术文档
  - 协作规范
  - 空白符号
  - 列表
  - 表格
  - 图形
  - 代码
  - 链接
  - 缩略语
  - 数字
tags:
  - 软件工程/技术文档
  - 技术/软件工程
author: 7Wate
date: 2024-08-07
---

## 空白符号

空白符号包括空格、空行等，其中空格分为半角空格和全角空格。

### 空格

- 使用半角空格，不使用全角空格；英文字符和阿拉伯数字用半角空格包围

> 这是一段□□□文本。❌
>
> 这是一段文本。
>
> 这是一段文本，包含中文、English□words□和□12345。

- 除缩进、列表级别、代码块和 Markdown 表格外，禁止连续使用半角空格。

- **禁止使用 Tab 替换空格。**

### 空行

- 不同段落间用一个空行隔开，不同排版格式之间（如标题和正文，正文和代码块，正文和表格等）也使用一个空行隔开。

```markdown
# 这是一个标题
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是第一段。
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是第二段。
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
```

- 禁止连续出现两个及以上的空行。

```markdown
这是一段文本。
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是另一段错误的文本。❌
```

### 其他

- 行宽在 80、120 字符中自由选择，原则上不超过 160 字符宽。

- 推荐使用空格进行缩进或对齐，禁止使用 Tab 键。

```markdown
- 列表项1
  - 子列表项1
  - 子列表项2
- 列表项2
```

## 列表

- 使用纵向列表表示多项信息。

```markdown
以下是我们需要考虑的事项：
- 项目预算
- 团队规模
- 项目时间线
- 预期成果
```

- 列表项的顺序重要时，使用有序列表。

```markdown
请按照以下步骤进行操作：
1. 打开电脑。
2. 打开浏览器。
3. 输入网址。
```

- 并列列表项中使用相似的句子结构，并保持标点符号一致。

```markdown
我们的团队成员包括：
- 李雷，负责产品设计。
- 韩梅梅，负责项目管理。
- Jim，负责软件开发。
```

- 使用清晰的、描述性的句子或短语来引出表。

```markdown
以下是我们团队的主要职责：
- 设计和开发新产品。
- 维护现有产品。
- 提供客户支持。
```

- 使用有序列表描述操作任务的步骤。

```markdown
使用该软件的步骤如下：
1. 下载并安装软件。
2. 运行软件并点击 "新建项目"。
3. 输入项目详情并保存。
4. 开始使用软件进行项目管理。
```

- 嵌套使用列表，最多不超过 3 级。

```markdown
本产品主要包括以下部分：
- 外壳
  - 上盖
  - 下盖
- 内部组件
  - CPU
  - 内存
  - 硬盘
```

## 表格

- 所有内容保持左对齐，内容尽量简练，避免长篇大段的说明，不出现空白的单元格，单元格内容避免重复。

```markdown
| 表头1   | 表头2   | 表头3   |
|:-------|:-------|:-------|
| 内容1   | 内容2   | 内容3   |
| 内容4   | 内容5   | 内容6   |
```

- 表格需要有表头描述，同一文档中相同类型表格的表头描述需要保持一致。

```markdown
| 姓名     | 年龄   | 职业   |
|:-------|:-----|:-----|
| 张三     | 25    | 程序员 |
| 李四     | 30    | 设计师 |
```

- 每个表格下都要空一行，空行的样式为正文。

```markdown
| 姓名     | 年龄   | 职业   |
|:-------|:-----|:-----|
| 张三     | 25    | 程序员 |
| 李四     | 30    | 设计师 |
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是正文部分
```

## 图形和图片

- **必须使用清晰可辨的图形图片。**
- 中文文档里图形图片上的文字建议都用中文，如果原图文字是其他语言，应该先做好图片本地化工作。
- 文字建议使用**免费开源可商用字体**，以免引入法律风险。同一文档内图形图片上的中文应该统一字体（如思源黑体），英文和数字也要统一字体（如 Times New Roman）。
- 图形图片中避免出现大段文字，描述性语言建议放到图外，用编号替代。
- 图形图片中包含缩略语时，需要在图说明中对缩略语进行解释。
- 图说明和图尽量保证在同一页中显示。
- 图片的命名建议使用描述性的文字。
- 插入图片时建议添加替代文本，从而改进文档的可访问性。

```markdown
![描述图片内容](/path/to/image.jpg "图片标题，可选填")

- **说明**：图1. 这是一幅示例图片。其中的文字全部使用了中文，并且字体统一为思源黑体。对于图中的缩略语，我们在这里进行解释：XYZ代表的是...
```

## 代码块和代码注释

- 如果代码块语言被支持，那么应该明确声明语言类型。

````markdown
  ```python
  # 这是一个 Python 示例
  print("Hello, World!")
  ```
````

- 代码块中出现的长命令应当按逻辑进行换行，并且注明需要换行的地方。

````markdown
  ```bash
  # 在这个长命令中，我们使用 \ 来进行换行
  command --option1 --option2 \
  --option3 --option4 --option5
  ```
````

- 代码块中的命令，如需参数替换，应该清晰标注。

````markdown
  ```bash
  # 在这个命令中，<username> 需要被你的用户名替换
  ssh <username>@example.com
  ```
````

- 代码块中不应当出现警告或者错误信息，除非它们是文章需要表达的内容。

````markdown
  ```python
  # 这个 Python 示例没有任何错误或警告
  def greet(name):
      print(f"Hello, {name}!")
  greet("World")
  ```
````

- 代码注释需要使用英文，并且注释要简洁明了，且必须准确。

````markdown
  ```python
  # Correct and concise comment: Print greeting
  print("Hello, World!")  
  ```
````

- 如果代码块中的注释和文章内容重复，那么优先使用代码块中的注释，同时去掉文章中的内容。

````markdown
  ```python
  # This comment explains the following code block
  print("Hello, World!")  # This line prints a greeting
  ```
````

## 链接和引用

- 链接和引用必须给出精确的位置信息。例如，如果你正在引用一个具体的 GitHub 代码行：

```markdown
看一下 [这个具体的代码行](https://github.com/user/repository/blob/master/file.py#L42) 来理解如何实现这个功能。
```

- 如果链接和引用的位置有更新，必须及时更新链接。

```markdown
由于最新的更新，参考 [新的代码实现](https://github.com/user/repository/blob/master/new_file.py#L50)。
```

- 链接和引用中出现的代码，必须使用代码块包围。

````markdown
参考以下代码实现：

  ```python
  def greet(name):
  ```
````

- 必须标注链接的类型，如文章、工具、命令等。

```markdown
阅读这篇 [文章](https://example.com/article) 来更深入地了解这个主题。
使用这个 [工具](https://example.com/tool) 来帮助你的开发工作。
运行以下 [命令](https://example.com/command) 来配置你的环境。
```

- 每个文件的引用必须声明来源，使用全称，不要使用相对路径或者绝对路径。

```markdown
引用自 [Python官方文档](https://docs.python.org/3/tutorial/index.html)，不是 `../tutorial/index.html` 或者 `/home/user/docs/tutorial/index.html`。
```

- 不能使用会失效的链接。

```markdown
请使用 [永久链接](https://example.com/permanent-link)，而不是 [会失效的链接](https://example.com/temporary-link)。
```

- 链接的文字应描述其链接的内容，而不应为「这里」、「此处」等模糊词汇。

```markdown
阅读 [Python教程](https://docs.python.org/3/tutorial/index.html)，而不是点击 [这里](https://docs.python.org/3/tutorial/index.html)。
```

## 缩略语

在编写中文技术文档时，我们常会用到两类缩略语：汉语缩略语和英语缩略语。

### 汉语缩略语

汉语缩略语是通过缩短和省略较长的中文词语来形成的新词。例如，「人大」是「人民大会堂」的缩略，而「重启」则是「重启动」的缩略。

**使用汉语缩略语时，我们要确保这些词在上下文中的含义清晰、准确，以避免产生歧义。**如果某个汉语缩略语并非大众常用或容易理解，我们在初次使用时应提供全称和相应的解释。例如，如果我们在文档中使用「绑核」作为「核心绑定」的缩略，我们需要在初次使用时指出：「本文将使用 ' 绑核 ' 作为 ' 核心绑定 ' 的缩略」。

### 英语缩略语

相较于汉语缩略语，英语缩略语种类繁多，数量众多。一般来说，它们分为三类：**首字母缩略词、字母词和缩写词。**

- 首字母缩略词：这类缩略词是由每个单词的首字母组合而成，且作为一个单词发音。如「NATO」（North Atlantic Treaty Organization），我们读作 /'neɪtoʊ/，而**非逐字母发音。**

- 字母词：与首字母缩略词类似，也是由每个词的首字母组成，但是按字母逐一发音。例如，「FBI」（Federal Bureau of Investigation），我们会读作 /'efbi:'aɪ/，而**非作为一个单词发音。**

- 缩写词：直接将较长的词语进行缩短形成新词。例如，「App」是「Application」的缩写词，「demo」则是「demonstration」的缩写词。我们读作 /'æp/，而**非逐字母发音。**

在使用英语缩略语时，我们需要注意以下几点：

- 在标题中，避免对英文缩略语进行解释，以免使标题过长，影响阅读。

- 在正文中，首次出现的英文缩略语需要提供其完整形式和对应的解释。例如，如果我们首次使用「AI」，我们需要指出：「AI（Artificial Intelligence，人工智能）」。

- 当使用缩略语代指某词时，必须在该词首次出现时告知读者，下文将以缩略语的形式称呼该词。

- 不要使用非标准的或可能引起混淆的缩略语，例如，「16c32g」不能用来表示「16 核、32GB」，「10w」也不能用来表示「10 万」。

## 数字

在中文语境中，数字有两种形式：第一种是汉字数字，如「二」、「十」等；第二种是阿拉伯数字，如「2」、「10」等。

### 汉字数字

**汉字数字主要用于表示概数、干支纪年、含有汉字数字的词语，以及突出庄重典雅的效果。**

- 概数表达：数字连用表示概数时，不用顿号隔开。例如： `三四十`。
- 年份简写：年份简写后的数字不应简写为两位数字。例如： `二〇二三` 而不是 `二三`。
- 月日的专名：含有月日的专名中，使用间隔号「·」将数字分开，并在前后加引号，避免歧义。例如： `"六·二六"`。
- 法律文书和财务票据：大写汉字数字用于法律文书和财务票据。例如： `肆仟贰佰叁拾肆元整`。
- 计量和编号：「零」用于计量，「〇」用于编号。例如： `十零个苹果`， `编号〇一〇二`。

| 适用场景                                                     | 示例                                                         |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| 数字连用表示的概数、含「几」的概数等                         | 三四个月、一二十个、十五六岁、五六万套、五六十年前、几千、二十几、一百几十、几十万分之一 |
| 干支纪年、农历月日、历史朝代纪年及其他传统上采用汉字形式的非公历纪年 | 腊月二十三、正月初五、八月十五中秋、秦文公四十四年、太平天国庚申十年九月二十三号、日本庆应三年、丙寅年十月十五日 |
| 汉语中长期使用且已稳定下来的包含汉字数字形式的词语           | 星期五、四氧化三铁、一方面、不二法门、二八年华、二百五、八国联军、五四运动、万一、一旦、四书五经、七上八下、不管三七二十一、半斤八两、「一·二八」事变、「一·二九」运动 |
| 希望突出庄重典雅的表达效果时                                 | 六方会谈（不写为「6 方会谈」）、十一届全国人大一次会议（不写为「11 届全国人大 1 次会议」） |

### 阿拉伯数字

**阿拉伯数字主要用于计量、编号、现代社会生活中的事物和现象，以及突出简洁醒目的效果。**

- 形式书写：使用半角形式书写，避免使用全角形式。例如： `2023` 而不是 `２０２３`。
- 分节符：使用半角逗号作为分节符。例如： `1,000,000` 而不是 `1000000`。
- 表达范围：表示数值范围时使用浪纹式连接号「～」或一字线连接号「—」。例如： `10～20` 或 `10—20`。

- 日期和时间：年月日和时分秒的表达顺序按照口语中的自然顺序。例如： `2023年6月26日` 或 `15:30:00`。
- 月日的专名：含有月日的专名中，使用间隔号「·」将数字分开，并在前后加引号，避免歧义。例如： `"6·26"`。

| 适用场景                                                     | 示例                                                         |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| 用于计量（即用于加、减、乘、除等数学运算）的数字，如正负整数、小数、百分比、比例、分数等。 | -126、34.05%、63%～67%、1:500、87/90                         |
| 当数值伴随有计量单位，如长度、容积、面积、体积、质量、温度、经纬度、音量、频率等，特别是当计量单位以字母表达时 | 524.5 km（524.5 千米）、53 MB（53 兆字节）、12 h（12 小时）  |
| 用于编号的数字                                               | - 电话号码：98888 - 邮政编码：100083 - 电子邮件地址：[xxx@163.com](mailto:xxx@163.com) - 网页地址：[http://127.0.0.1](http://127.0.0.1/) - 章节编号：4.1.2 - 产品型号：PH-3000 型计算机 - 产品序列号：C84XB-JYVFD-P7HC4-6XKRJ-7M6XH - 汽车号牌：京 A00001 - 公交车号： 302 路公交车 - 道路编号：101 国道 - 公文编号：国办发 [1987]9 号 - 图书编号：ISBN 978-7-80184-224-4 - 刊物编号：CN11-1389 - 单位注册号：02050214 - 行政许可登记编号：0684D10004-828 |
| 现代社会生活中出现的事物、现象、事件，其名称的书写形式中包含阿拉伯数字，已经广泛使用而稳定下来 | 4G 手机、MP4 播放器、维生素 B12、「5·27」事件                |
| 希望突出简洁醒目的表达效果时                                 | 北京时间 2020 年 10 月 1 日 12 点整                          |

### 单位符号

- 汉字名称：建议用汉字名称代替单位符号。例如： `三米` 而不是 `3m`。

- 间隔空格：数值和单位之间通常需要空一个半角空格，但有例外情况。例如： `3□kg`。

- 角度、摄氏度和百分号：角度、摄氏度和百分号的单位与数值之间不空格。例如： `45°`、 `20°C` 或 `50%`。

- 英尺符号和英寸符号：英尺符号和英寸符号与数值之间不空格。例如： `6'2"`。

| 单位形式             | 示例           |
| -------------------- | -------------- |
| 汉字名称             | 三米           |
| 间隔空格             | 3□kg           |
| 角度、摄氏度和百分号 | 45°、20°C、50% |
| 英尺符号和英寸符号   | 6'2"           |

## 拼写

中文技术文档既包含中文内容，也可能包含英文内容。因此，我们必须避免以下几种拼写错误。

- 禁止简体中文和繁体中文的混用。

> 这款软件的颜色设计很独特，它的界面顏色是由用户自己选择的。❌
>
> 正确示例：这款软件的颜色设计很独特，它的界面颜色是由用户自己选择的。

- 禁止出现中英文错别字。错别字包括错字和别字。

> 这款软件使用 MySOL 数据库存储数据。❌
>
> 这款软件使用 MySQL 数据库存储数据。

### 英文的大小写形式

- 英文大小写形式不能写错。

> 用户可以在 mysql 数据库中创建新的表。❌
>
> 用户可以在 MySQL 数据库中创建新的表。

- 当中文句子中夹有英文单词或词组时，无论该英文单词或词组位于中文句子的开头、中间还是末尾，普通单词、词组必须小写；专有名词等在英文中必须大写的单词或词组，保留其大写形式。

> 在 SQL 语句中，你可以使用 "SELECT" 语句获取数据。❌
>
> 在 SQL 语句中，你可以使用 "select" 语句获取数据。

- 当中文句子中夹有完整的英文句子时，无论该英文句子位于中文句子的开头、中间还是末尾，其首字母均保留大写形式。

> 如需更多信息，请参阅 "in this chapter, we will learn how to create tables."❌
>
> 如需更多信息，请参阅 "In this chapter, we will learn how to create tables."

## 语法

### 成分残缺

在编写技术文档时，务必确保语句的成分完整。每个句子都应该有一个明确的主语和谓语，以及必要的宾语和定语。

> 会话保持：在应用程序没有提供会话保持的功能下，HAProxy 可以提供该项功能。❌
>
> 会话保持：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能。

### 搭配不当

确保你的句子中使用的词汇是搭配恰当的。不正确的词汇搭配可能会让读者混淆，影响他们对你的文档的理解。

> HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，并仍然负责该项目的维护，该在开源社区提供免费和版本迭代。❌
>
> HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。

### 倍数表达

技术文档中表达倍数建议遵循以下规范。

- 数值的增加必须明确使用「增加了」或「增加到」，不能只使用「增加」。「了」表增量，「到」表定量。
- 数值的减少必须明确使用「降低了」或「降低到」，不能只使用「降低」。「了」表增量，「到」表定量。
- 不能用「降低 N 倍」或「减少 N 倍」的表示法，要用「降低百分之几」或「减少百分之几」。

| 表述方式 | 示例                       | 校验 |
| -------- | -------------------------- | ---- |
| 增加了   | 处理速度增加了两倍。       | ✔    |
| 只用增加 | 处理速度增加两倍。         | ❌    |
| 增加到   | 处理速度增加到两倍。       | ✔    |
| 只用增加 | 处理速度增加两倍。         | ❌    |
| 降低了   | 处理速度降低了五十百分点。 | ✔    |
| 降低 N 倍  | 处理速度降低两倍。         | ❌    |

### 成分多余

避免在句子中使用不必要的词汇或短语，这可能会使句子变得冗长和复杂，影响其清晰度和可读性。

> 根据官方建议，目前稳定版本的 HAProxy 为稳定版 2.0 特性。❌
>
> 官方目前建议使用 HAProxy 稳定版本 2.0。

### 句式杂糅

避免在一个句子中混合使用多种句式。尽量保持句子简洁明了，如果需要表达的信息较多，可以考虑分解为多个句子。

> 当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群并用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若 DM-master 可用节点数超过部署节点的半数，即可正常提供服务。❌
>
> 当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群。该 DM-master 集群用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点。该 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若可用的 DM-master 节点数超过部署节点的半数，即可正常提供服务。