空白符号
空白符号包括空格、空行等，其中空格分为半角空格和全角空格。
空格
- 使用半角空格，不使用全角空格；英文字符和阿拉伯数字用半角空格包围
这是一段□□□文本。❌
这是一段文本。
这是一段文本，包含中文、English□words□和□12345。
-
除缩进、列表级别、代码块和 Markdown 表格外，禁止连续使用半角空格。
-
禁止使用 Tab 替换空格。
空行
- 不同段落间用一个空行隔开，不同排版格式之间（如标题和正文，正文和代码块，正文和表格等）也使用一个空行隔开。
# 这是一个标题
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是第一段。
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是第二段。
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□- 禁止连续出现两个及以上的空行。
这是一段文本。
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是另一段错误的文本。❌其他
-
行宽在 80、120 字符中自由选择，原则上不超过 160 字符宽。
-
推荐使用空格进行缩进或对齐，禁止使用 Tab 键。
- 列表项1
- 子列表项1
- 子列表项2
- 列表项2列表
- 使用纵向列表表示多项信息。
以下是我们需要考虑的事项：
- 项目预算
- 团队规模
- 项目时间线
- 预期成果- 列表项的顺序重要时，使用有序列表。
请按照以下步骤进行操作：
1. 打开电脑。
2. 打开浏览器。
3. 输入网址。- 并列列表项中使用相似的句子结构，并保持标点符号一致。
我们的团队成员包括：
- 李雷，负责产品设计。
- 韩梅梅，负责项目管理。
- Jim，负责软件开发。- 使用清晰的、描述性的句子或短语来引出表。
以下是我们团队的主要职责：
- 设计和开发新产品。
- 维护现有产品。
- 提供客户支持。- 使用有序列表描述操作任务的步骤。
使用该软件的步骤如下：
1. 下载并安装软件。
2. 运行软件并点击 "新建项目"。
3. 输入项目详情并保存。
4. 开始使用软件进行项目管理。- 嵌套使用列表，最多不超过 3 级。
本产品主要包括以下部分：
- 外壳
- 上盖
- 下盖
- 内部组件
- CPU
- 内存
- 硬盘表格
- 所有内容保持左对齐，内容尽量简练，避免长篇大段的说明，不出现空白的单元格，单元格内容避免重复。
| 表头1 | 表头2 | 表头3 |
|:-------|:-------|:-------|
| 内容1 | 内容2 | 内容3 |
| 内容4 | 内容5 | 内容6 |- 表格需要有表头描述，同一文档中相同类型表格的表头描述需要保持一致。
| 姓名 | 年龄 | 职业 |
|:-------|:-----|:-----|
| 张三 | 25 | 程序员 |
| 李四 | 30 | 设计师 |- 每个表格下都要空一行，空行的样式为正文。
| 姓名 | 年龄 | 职业 |
|:-------|:-----|:-----|
| 张三 | 25 | 程序员 |
| 李四 | 30 | 设计师 |
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
这是正文部分图形和图片
- 必须使用清晰可辨的图形图片。
- 中文文档里图形图片上的文字建议都用中文，如果原图文字是其他语言，应该先做好图片本地化工作。
- 文字建议使用免费开源可商用字体，以免引入法律风险。同一文档内图形图片上的中文应该统一字体（如思源黑体），英文和数字也要统一字体（如 Times New Roman）。
- 图形图片中避免出现大段文字，描述性语言建议放到图外，用编号替代。
- 图形图片中包含缩略语时，需要在图说明中对缩略语进行解释。
- 图说明和图尽量保证在同一页中显示。
- 图片的命名建议使用描述性的文字。
- 插入图片时建议添加替代文本，从而改进文档的可访问性。
- **说明**：图1. 这是一幅示例图片。其中的文字全部使用了中文，并且字体统一为思源黑体。对于图中的缩略语，我们在这里进行解释：XYZ代表的是...代码块和代码注释
- 如果代码块语言被支持，那么应该明确声明语言类型。
```python
# 这是一个 Python 示例
print("Hello, World!")
```- 代码块中出现的长命令应当按逻辑进行换行，并且注明需要换行的地方。
```bash
# 在这个长命令中，我们使用 \ 来进行换行
command --option1 --option2 \
--option3 --option4 --option5
```- 代码块中的命令，如需参数替换，应该清晰标注。
```bash
# 在这个命令中，<username> 需要被你的用户名替换
ssh <username>@example.com
```- 代码块中不应当出现警告或者错误信息，除非它们是文章需要表达的内容。
```python
# 这个 Python 示例没有任何错误或警告
def greet(name):
print(f"Hello, {name}!")
greet("World")
```- 代码注释需要使用英文，并且注释要简洁明了，且必须准确。
```python
# Correct and concise comment: Print greeting
print("Hello, World!")
```- 如果代码块中的注释和文章内容重复，那么优先使用代码块中的注释，同时去掉文章中的内容。
```python
# This comment explains the following code block
print("Hello, World!") # This line prints a greeting
```链接和引用
- 链接和引用必须给出精确的位置信息。例如，如果你正在引用一个具体的 GitHub 代码行：
看一下 [这个具体的代码行](https://github.com/user/repository/blob/master/file.py#L42) 来理解如何实现这个功能。- 如果链接和引用的位置有更新，必须及时更新链接。
由于最新的更新，参考 [新的代码实现](https://github.com/user/repository/blob/master/new_file.py#L50)。- 链接和引用中出现的代码，必须使用代码块包围。
参考以下代码实现：
```python
def greet(name):
```- 必须标注链接的类型，如文章、工具、命令等。
阅读这篇 [文章](https://example.com/article) 来更深入地了解这个主题。
使用这个 [工具](https://example.com/tool) 来帮助你的开发工作。
运行以下 [命令](https://example.com/command) 来配置你的环境。- 每个文件的引用必须声明来源，使用全称，不要使用相对路径或者绝对路径。
引用自 [Python官方文档](https://docs.python.org/3/tutorial/index.html)，不是 `../tutorial/index.html` 或者 `/home/user/docs/tutorial/index.html`。- 不能使用会失效的链接。
请使用 [永久链接](https://example.com/permanent-link)，而不是 [会失效的链接](https://example.com/temporary-link)。- 链接的文字应描述其链接的内容，而不应为「这里」、「此处」等模糊词汇。
阅读 [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 - 网页地址：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 节点数超过部署节点的半数，即可正常提供服务。