467 lines
21 KiB
Markdown
467 lines
21 KiB
Markdown
---
|
||
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
|
||
|
||
|
||
- **说明**：图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 节点数超过部署节点的半数，即可正常提供服务。
|