wiki/5.文档内容.md at e268fc074bf406960aa55bc3284e34c3b052f2e7

zhouzhongping/wiki

Fork 0

7Wate e268fc074b

项目：重构

2024-10-13 20:52:05 +08:00

21 KiB

Raw Blame History

title

description

keywords

空白符号

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

空格

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

这是一段□□□文本。❌

这是一段文本。

这是一段文本，包含中文、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）。
图形图片中避免出现大段文字，描述性语言建议放到图外，用编号替代。
图形图片中包含缩略语时，需要在图说明中对缩略语进行解释。
图说明和图尽量保证在同一页中显示。
图片的命名建议使用描述性的文字。
插入图片时建议添加替代文本，从而改进文档的可访问性。

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

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

21 KiB Raw Blame History Unescape Escape