文档：中文文档写作指南 2.0
This commit is contained in:
parent
ccad59e953
commit
9c34b20058
@ -1,74 +0,0 @@
|
||||
---
|
||||
id: 名称命名
|
||||
title: 名称命名
|
||||
sidebar_position: 6
|
||||
data: 2022年3月8日
|
||||
---
|
||||
|
||||
## 文件命名
|
||||
|
||||
本节以 Markdown 语言编写的技术文档为例，介绍源文件的命名规范。如下所示。
|
||||
|
||||
- 文件名应该能对文档内容进行简要概括。
|
||||
- 文件名不宜过长。
|
||||
- 当文件名由多个英文单词组成时，单词中间应当由短划线“-”隔开。
|
||||
- 不建议在文件名中使用下划线“_”。在 URL 中出现下划线不利于搜索引擎优化，且下划线在部分 Markdown 实现中是修饰字符。
|
||||
- 当文件名由多个英文单词组成时，文件名建议使用全小写单词，全大写亦可接受，如 FAQ.md。
|
||||
- 文件名禁止大小写混用。
|
||||
- 文件后缀名应当使用小写形式。
|
||||
- Markdown 文件应当使用“.md”后缀，“.markdown”亦可接受，但要保证风格统一。
|
||||
|
||||
## 产品命名
|
||||
|
||||
一个公司命名其产品（或周边工具）时应遵循一定的风格规范，不可随意取名。否则，重则有法律风险（重名问题），轻则影响对外品牌输出。
|
||||
|
||||
建议在全公司范围内，建立产品命名的统一流程，维护一份统一的产品名称表。
|
||||
|
||||
## 名称使用
|
||||
|
||||
中文技术文档中使用一些专用名称时，应注意如下规范。
|
||||
|
||||
### 国外公司、品牌或产品名称使用规范
|
||||
|
||||
中文文档中指称国外公司、品牌或产品名称时，建议遵循以下规范：
|
||||
|
||||
- 对于**中文读者熟知其中文官方译名**的公司、品牌或产品名称，只需用**中文官方译名**指称
|
||||
- 对于**中文读者不熟悉、但有中文官方译名**的公司、品牌或产品名称，建议用“**中文官方译名 (英文官方名称)**”形式
|
||||
- 对于**无中文官方译名**的公司、品牌或产品名称，建议直接用**英文**指称，且必须使用**正确的大小写**形式
|
||||
- 【错误示例】mysql、github、tiktok、wechat
|
||||
- 【正确示例】MySQL、GitHub、TikTok、WeChat
|
||||
|
||||
注意事项：
|
||||
|
||||
- 判断中文大众读者是否熟知某名称具有主观性。如果不确定中文读者是否熟知某名称，建议优先考虑“中文官方译名 (英文官方名称)”形式。
|
||||
- 在使用“中文官方译名 (英文官方名称)”形式时，只需在第一次出现该名称的时候使用完整形式，之后再出现时使用中文官方译名即可。
|
||||
|
||||
### 公司、品牌或产品名称列表
|
||||
|
||||
下表仅提供参考示例，不同公司可视自身内容情况作相应的调整。
|
||||
|
||||
> 下表待补充，欢迎贡献！
|
||||
|
||||
|
||||
|
||||
| 中文读者熟知中文官方译名 | 中文读者不熟悉、但有中文官方译名 | 无中文官方译名 |
|
||||
| ------------------------ | -------------------------------- | -------------- |
|
||||
| 微软 | 威睿 (VMware) | GitHub |
|
||||
| 苹果 | 塔多思 (Trados) | SDL |
|
||||
| 甲骨文 | 雪佛龙 (Chevron) | MySQL |
|
||||
| 沃尔玛 | 埃克森美孚 (Exxon Mobil) | Alphabet |
|
||||
| 亚马逊 | 大众 (Volkswagen) | MongoDB |
|
||||
| 惠普 | 戴姆勒 (Daimler) | Azure |
|
||||
| 宝马 | 西门子 (Siemens) | |
|
||||
| 波音 | 软银 (SoftBank) | |
|
||||
| 雀巢 | 东芝 (Toshiba) | |
|
||||
| 宝洁 | 思科 (Cisco) | |
|
||||
| 强生 | | |
|
||||
| 索尼 | | |
|
||||
| 百事 | | |
|
||||
| 可口可乐 | | |
|
||||
| 高盛 | | |
|
||||
| 佳能 | | |
|
||||
| 推特 | | |
|
||||
| 脸书 | | |
|
||||
| 领英 | | |
|
||||
77
wiki/getting-started/文档/命名约定.md
Normal file
77
wiki/getting-started/文档/命名约定.md
Normal file
@ -0,0 +1,77 @@
|
||||
---
|
||||
title: 命名约定
|
||||
description: 文档命名约定
|
||||
keywords:
|
||||
- 文档
|
||||
- 命名
|
||||
- 约定
|
||||
tags:
|
||||
- 标签
|
||||
sidebar_position: 2
|
||||
author: 7Wate
|
||||
date: 2023-06-26
|
||||
---
|
||||
|
||||
## 文件命名
|
||||
|
||||
在以 Markdown 语言编写的技术文档中，源文件的命名应遵循以下规范：
|
||||
|
||||
- 文件名应简明地概述文档内容。
|
||||
- 文件名长度应适中，避免过长。
|
||||
- 当文件名由多个英文单词组成时，用短划线「-」连接。
|
||||
- 在文件名中避免使用下划线「_」，它在URL中可能影响搜索引擎优化，并可能被某些 Markdown 实现当作修饰字符。
|
||||
- 多个单词组成的文件名，全小写或全大写均可，但**避免大小写混用**，如`faq.md`或`FAQ.md`。
|
||||
- 文件扩展名应为小写。
|
||||
- Markdown文件应使用「.md」后缀，虽然「.markdown」也可以接受，但应保证整体文件风格的统一。
|
||||
|
||||
| 文件名 | 内容描述 |
|
||||
| ------------------------------ | -------------------------------------- |
|
||||
| `introduction-to-python.md` | 此文件可能包含有关Python语言的基础知识 |
|
||||
| `database-connection-guide.md` | 这是一个指南，说明如何连接到数据库 |
|
||||
| `faq.md` | 这是一个常见问题解答文件 |
|
||||
| `README.md` | 这是一个项目介绍文件 |
|
||||
|
||||
## 产品命名
|
||||
|
||||
企业为其产品或工具命名时，应确保遵循一致的风格和规范，以避免可能的法律风险（如重名问题）和品牌形象受损。推荐组织设立统一的产品命名流程，并维护一个组织内部产品名称列表。
|
||||
|
||||
| 英文产品名称 | 中文产品名称 |
|
||||
| ---------------- | ---------------- |
|
||||
| Microsoft Office | 微软办公软件 |
|
||||
| Photoshop | 阿多比 Photoshop |
|
||||
|
||||
## 名称使用
|
||||
|
||||
在中文技术文档中，应遵守以下专用名称使用规范：
|
||||
|
||||
### 国外组织、品牌或产品名称使用规范
|
||||
|
||||
- 当中文读者熟知其中文官方译名时，使用**中文官方译名**。
|
||||
- 当中文读者不熟悉、但有中文官方译名时，使用「**中文官方译名 (英文官方名称)**」格式。
|
||||
- 对于没有中文官方译名的名称，直接用**英文**指称，务必保持正确的大小写形式。
|
||||
|
||||
注意，判断是否「中文读者熟知」具有主观性，如有疑虑，建议优先使用「**中文官方译名 (英文官方名称)**」格式。在首次提到该名称时，使用完整格式，之后的提及可只使用中文官方译名。
|
||||
|
||||
### 组织、品牌或产品名称列表
|
||||
|
||||
| 中文读者熟知中文官方译名 | 中文读者不熟悉、但有中文官方译名 | 无中文官方译名 |
|
||||
| ------------------------ | -------------------------------- | -------------- |
|
||||
| 微软 (Microsoft) | 威睿 (VMware) | GitHub |
|
||||
| 苹果 (Apple) | 塔多思 (Trados) | SDL |
|
||||
| 甲骨文 (Oracle) | 雪佛龙 (Chevron) | MySQL |
|
||||
| 沃尔玛 (Walmart) | 埃克森美孚 (Exxon Mobil) | Alphabet |
|
||||
| 亚马逊 (Amazon) | 大众 (Volkswagen) | MongoDB |
|
||||
| 惠普 (HP) | 戴姆勒 (Daimler) | Azure |
|
||||
| 宝马 (BMW) | 西门子 (Siemens) | Jira |
|
||||
| 波音 (Boeing) | 软银 (SoftBank) | Slack |
|
||||
| 雀巢 (Nestle) | 东芝 (Toshiba) | Docker |
|
||||
| 宝洁 (Procter & Gamble) | 思科 (Cisco) | Kubernetes |
|
||||
| 强生 (Johnson & Johnson) | 瑞声 (Resound) | Ansible |
|
||||
| 索尼 (Sony) | 罗克韦尔 (Rockwell Automation) | GitLab |
|
||||
| 百事 (Pepsi) | 三洋 (Sanyo) | TensorFlow |
|
||||
| 可口可乐 (Coca-Cola) | 格雷普 (Crepe) | Elasticsearch |
|
||||
| 高盛 (Goldman Sachs) | 微步 (Microstep) | PyTorch |
|
||||
| 佳能 (Canon) | 三菱 (Mitsubishi) | Apache Kafka |
|
||||
| 推特 (Twitter) | 亚都 (Audu) | Redis |
|
||||
| 脸书 (Facebook) | 逸碧 (Epyc) | Apache Spark |
|
||||
| 领英 (LinkedIn) | 萨博 (Saab) | Terraform |
|
||||
@ -1,77 +0,0 @@
|
||||
---
|
||||
id: 拼写与语法
|
||||
title: 拼写与语法
|
||||
sidebar_position: 7
|
||||
data: 2022年3月8日
|
||||
---
|
||||
|
||||
## 拼写
|
||||
|
||||
中文技术文档既包含中文内容，也可能包含英文内容，因此应严格避免以下几种拼写错误。
|
||||
|
||||
- 简体中文和繁体中文不能混用。
|
||||
- 禁止出现中英文错别字。错别字包括错字和别字，两者均不能出现。
|
||||
- 错字是将某个字写错，这个错字是人为编造出来的，无任何意义。如将 MySQL 写成 MySOL。
|
||||
- 别字是指写出的字与正确的字形近或音近，但意思却不同。如将 cooperate 写成 corporate，将 authorization 写成 authentication。
|
||||
|
||||
### 英文的大小写形式
|
||||
|
||||
- 英文大小写形式不能写错。如不能写成 mysql 数据库，应该写成 MySQL 数据库，具体参考[名称使用](https://zh-style-guide.readthedocs.io/zh_CN/latest/名称与命名/名称使用.html#id2)一节。
|
||||
- 当中文句子中夹有英文单词或词组时，无论该英文单词或词组位于中文句子的开头、中间还是末尾，**普通单词、词组必须小写**；**专有名词等在英文中必须大写的单词或词组，保留其大写形式**。
|
||||
- 【示例一】change 和 transform 意义不同。
|
||||
- 【示例二】这个数据库有不错的 MySQL 兼容性。
|
||||
- 当中文句子中夹有完整的英文句子时，无论该英文句子位于中文句子的开头、中间还是末尾，**其首字母均保留大写形式**。
|
||||
- 【示例一】Follow your fear 是我的座右铭。
|
||||
- 【示例二】他经常与人说“Never set a limit to yourself.”。
|
||||
|
||||
## 语法
|
||||
|
||||
本节列举了中文技术文档中常见的几种语法错误，文档工程师及审校者应着重注意。
|
||||
|
||||
> 欢迎各位补充你身边的案例。
|
||||
|
||||
### 成分残缺
|
||||
|
||||
【示例一】会话保持：在应用程序没有提供会话保持的功能下，HAProxy 可以提供该项功能。
|
||||
|
||||
【建议】会话保持：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能。
|
||||
|
||||
### 搭配不当
|
||||
|
||||
【示例一】HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，并仍然负责该项目的维护，该在开源社区提供免费和版本迭代。
|
||||
|
||||
【存在的问题】“并仍然负责”的主语是 Willy Tarreau，不是 HAProxy。
|
||||
|
||||
【建议】HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。
|
||||
|
||||
### 用词不当
|
||||
|
||||
#### 倍数表达
|
||||
|
||||
技术文档中表达倍数建议遵循以下规范。
|
||||
|
||||
- **数值的增加必须明确使用“增加了”或“增加到”，不能只使用“增加”。“了”表增量，“到”表定量。**
|
||||
- 【错误示例】增加两倍
|
||||
- 【正确示例一】增加了两倍──即过去为一，现在为三。
|
||||
- 【正确示例二】增加到过去的两倍──即过去为一，现在为二。
|
||||
- **数值的减少必须明确使用“降低了”或“降低到”，不能只使用“降低”。“了”表增量，“到”表定量。**
|
||||
- 【错误示例】降低 80%
|
||||
- 【正确示例一】降低了 80%──即原来是一百，现在是二十。
|
||||
- 【正确示例二】降低到 80%──即原来是一百，现在是八十。
|
||||
- **不能用“降低 N 倍”或“减少 N 倍”的表示法，要用“降低百分之几”或“减少百分之几”。**
|
||||
|
||||
### 成分多余
|
||||
|
||||
【示例一】根据官方建议，目前稳定版本的 HAProxy 为稳定版 [2.0 特性](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。
|
||||
|
||||
【解释】官方目前建议使用 HAProxy 稳定版本 2.0，2.0 特性可以参考此链接。
|
||||
|
||||
【建议】官方目前建议使用 [HAProxy 稳定版本 2.0](https://www.haproxy.com/blog/haproxy-2-0-and-beyond/)。
|
||||
|
||||
### 句式杂糅
|
||||
|
||||
【示例一】当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群并用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若 DM-master 可用节点数超过部署节点的半数，即可正常提供服务。
|
||||
|
||||
【解释】适当断句，明确主语，避免句式杂糅。
|
||||
|
||||
【建议】当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群。该 DM-master 集群用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点。该 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若可用的 DM-master 节点数超过部署节点的半数，即可正常提供服务。
|
||||
@ -1,431 +1,458 @@
|
||||
---
|
||||
id: 文档内容
|
||||
title: 文档内容
|
||||
description: 文档内容
|
||||
keywords:
|
||||
- 文档
|
||||
- 内容
|
||||
tags:
|
||||
- 文档
|
||||
sidebar_position: 4
|
||||
data: 2022年3月8日
|
||||
author: 7Wate
|
||||
date: 2023-06-26
|
||||
---
|
||||
|
||||
## 空白符号
|
||||
|
||||
空白符号包括空格、空行等，其中空格分为半角空格和全角空格。
|
||||
|
||||
### 空白的使用
|
||||
### 空格
|
||||
|
||||
技术文档中使用空白符号建议遵循以下规范。
|
||||
- 使用半角空格，不使用全角空格；英文字符和阿拉伯数字用半角空格包围
|
||||
|
||||
| 空白类型 | 相应规范 |
|
||||
| -------- | ------------------------------------------------------------ |
|
||||
| 空格 | - 禁止使用全角空格，**一律使用半角空格**。 - 中文字符（包括汉字和中文标点符号）和中文字符之间禁止空半角空格。 - **英文字符和阿拉伯数字**一般使用半角格式，所以应使用半角空格包围，以下情况例外：1）位于句首时，左边空格省略； 2）其右侧为半角标点或全角标点时，右边空格省略。 - 除表示缩进、列表级别、代码块中固有空格、Markdown 表格中的空格外，禁止连续出现两个及以上的半角空格。 - 不建议使用 Tab（制表符）替换空格。 |
|
||||
| 空行 | - 不同段落间建议使用一个空行隔开。 - 不同排版格式之间建议使用一个空行隔开，如标题与紧跟着的正文之间，正文与代码块之间、正文与表格之间等。 - 禁止连续出现两个及以上的空行。 |
|
||||
| 其他 | 行宽：相同排版格式内保持一致即可，可自由在 80、120 字符中选择，原则上不超过 160 字符宽。 |
|
||||
> 这是一段□□□文本。❌
|
||||
>
|
||||
> 这是一段文本。
|
||||
>
|
||||
> 这是一段文本，包含中文、English□words□和□12345。
|
||||
|
||||
### Tab 和空格的使用
|
||||
- 除缩进、列表级别、代码块和 Markdown 表格外，禁止连续使用半角空格。
|
||||
|
||||
技术文档中经常使用 Tab 键和空格键进行缩进和对齐。由于在不同的编辑器里 Tab 的默认长度可能不一致，用 Tab 键设置缩进可能导致格式混乱。如果使用空格键设置缩进，则用任何编辑器打开文档都会显示一样的对齐效果。
|
||||
- **禁止使用 Tab 替换空格。**
|
||||
|
||||
因此建议：
|
||||
### 空行
|
||||
|
||||
- 使用空格键而不用 Tab 键进行缩进或对齐。
|
||||
- 使用 Tab 键缩进是可以接受的，但**禁止混用 Tab 和空格**进行缩进。
|
||||
- 在 Visual Studio Code 等编辑器里统一设置一个 Tab 等于四个半角空格。
|
||||
- 不同段落间用一个空行隔开，不同排版格式之间（如标题和正文，正文和代码块，正文和表格等）也使用一个空行隔开。
|
||||
|
||||
```markdown
|
||||
# 这是一个标题
|
||||
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
|
||||
这是第一段。
|
||||
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
|
||||
这是第二段。
|
||||
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
|
||||
```
|
||||
|
||||
- 禁止连续出现两个及以上的空行。
|
||||
|
||||
```markdown
|
||||
这是一段文本。
|
||||
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
|
||||
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
|
||||
这是另一段错误的文本。❌
|
||||
```
|
||||
|
||||
### 其他
|
||||
|
||||
- 行宽在 80、120 字符中自由选择，原则上不超过 160 字符宽。
|
||||
|
||||
- 推荐使用空格进行缩进或对齐，禁止使用 Tab 键。
|
||||
|
||||
```markdown
|
||||
- 列表项1
|
||||
- 子列表项1
|
||||
- 子列表项2
|
||||
- 列表项2
|
||||
```
|
||||
|
||||
## 列表
|
||||
|
||||
当有 3 项或更多重要信息需要展示时，纵向列表是最清晰且吸引眼球的方式。但如果项目少于 3 项且无需特别强调，将其直接放在句子中通常效果更好。
|
||||
- 使用纵向列表表示多项信息。
|
||||
|
||||
也可以创建多级嵌套列表，在某一级别下另起一行，缩进**四个空格**即可开始更低级别的列表。
|
||||
```markdown
|
||||
以下是我们需要考虑的事项：
|
||||
- 项目预算
|
||||
- 团队规模
|
||||
- 项目时间线
|
||||
- 预期成果
|
||||
```
|
||||
|
||||
### 无序列表和有序列表
|
||||
- 列表项的顺序重要时，使用有序列表。
|
||||
|
||||
技术文档中的列表分为有序列表 (ordered list) 和无序列表 (unordered list) 两种。一般而言，**当列表项之间的顺序不重要时，使用无序列表；当各项之间的顺序很重要时，使用有序列表。**
|
||||
```markdown
|
||||
请按照以下步骤进行操作：
|
||||
1. 打开电脑。
|
||||
2. 打开浏览器。
|
||||
3. 输入网址。
|
||||
```
|
||||
|
||||
【无序列表示例】
|
||||
- 并列列表项中使用相似的句子结构，并保持标点符号一致。
|
||||
|
||||
目前，TiDB 数据库使用了以下组件：
|
||||
```markdown
|
||||
我们的团队成员包括：
|
||||
- 李雷，负责产品设计。
|
||||
- 韩梅梅，负责项目管理。
|
||||
- Jim，负责软件开发。
|
||||
```
|
||||
|
||||
- Prometheus Server：用于收集和存储时间序列数据。
|
||||
- Client 代码库：用于定制程序中需要的 Metric。
|
||||
- Alertmanager：用于实现报警机制。
|
||||
- 使用清晰的、描述性的句子或短语来引出表。
|
||||
|
||||
【有序列表示例】
|
||||
```markdown
|
||||
以下是我们团队的主要职责：
|
||||
- 设计和开发新产品。
|
||||
- 维护现有产品。
|
||||
- 提供客户支持。
|
||||
```
|
||||
|
||||
解决办法：
|
||||
- 使用有序列表描述操作任务的步骤。
|
||||
|
||||
1. 编辑数据源文件。
|
||||
2. 手动创建所有的表。
|
||||
3. 设置参数跳过检查。
|
||||
```markdown
|
||||
使用该软件的步骤如下：
|
||||
1. 下载并安装软件。
|
||||
2. 运行软件并点击 "新建项目"。
|
||||
3. 输入项目详情并保存。
|
||||
4. 开始使用软件进行项目管理。
|
||||
```
|
||||
|
||||
有序列表的使用场景较少。当列表项的内容是以下几种时，应该使用有序列表。
|
||||
- 嵌套使用列表，最多不超过 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 安全特性，TiDB 不支持的功能有如下几种： - 外部身份验证方式 - 列级别权限设置 - 证书验证身份方式 |
|
||||
| 4. 使用清晰的、描述性的句子或短语来引出列表。 | 状态可以通过 store 的 state_name 来确定： - Up：这个 store 正常服务 - Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 - Down：超过一小时没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 | 你可以通过 store 的 state_name 确定其状态： - Up：这个 store 正常服务 - Disconnected：当前没有检测到这个 store 的心跳，可能是故障或网络连接中断 - Down：超过一小时没有收到 store 心跳，此时 PD 会为这个 store 上的数据添加副本 |
|
||||
| 5. 并列列表项中保持标点符号一致。 若列表项是句子，那么每一项建议以句号结尾； 若列表项是词组，则不建议以任何标点结尾； 若列表项既有词组又有句子，则建议统一以句号结尾。 | 【例一】TiDB Binlog 支持以下功能场景： - 数据同步。 - 实时备份和恢复。 【例二】指定数据源的相关信息： - 在 Name 处，为数据源指定一个名称。 - 在 Type 处，选择 Prometheus。 - 在 URL 处，指定 Prometheus 的 IP 地址。 - 其他字段 | 【例一】TiDB Binlog 支持以下功能场景： - 数据同步 - 实时备份和恢复 【例二】指定数据源的相关信息： - 在 Name 处，为数据源指定一个名称。 - 在 Type 处，选择 Prometheus。 - 在 URL 处，指定 Prometheus 的 IP 地址。 - 其他字段。 |
|
||||
| 6. 不要滥用无序列表，否则会导致它们失去应有的效果。 | 无 | 无 |
|
||||
| 7. 避免嵌套使用列表，这样通常会显得冗长复杂。 如果一定要表现多层级的列表，建议最多不超过 3 级，且每一级都要用不同样式的小圆点。 | 无 | 无 |
|
||||
| 8. 一个操作任务的步骤描述通常要使用有序列表，为方便用户记忆，建议严格限制列表项在 7 个以下，最多不要超过 9 个步骤。 | 无 | 无 |
|
||||
```markdown
|
||||
本产品主要包括以下部分：
|
||||
- 外壳
|
||||
- 上盖
|
||||
- 下盖
|
||||
- 内部组件
|
||||
- CPU
|
||||
- 内存
|
||||
- 硬盘
|
||||
```
|
||||
|
||||
## 表格
|
||||
|
||||
技术文档中使用表格建议遵循以下规范。
|
||||
- 所有内容保持左对齐，内容尽量简练，避免长篇大段的说明，不出现空白的单元格，单元格内容避免重复。
|
||||
|
||||
1. 样式规范
|
||||
```markdown
|
||||
| 表头1 | 表头2 | 表头3 |
|
||||
|:-------|:-------|:-------|
|
||||
| 内容1 | 内容2 | 内容3 |
|
||||
| 内容4 | 内容5 | 内容6 |
|
||||
```
|
||||
|
||||
- 单元格中的所有内容都**建议保持左对齐**。
|
||||
- 所有表格都需要有表头描述，即表格第一行中描述各列内容的短语。
|
||||
- 保证表格同一行的单元格不跨页。
|
||||
- 每个表格下都要空一行，这一空行的样式为正文。如遇到换页的情况，表格后的空行在新页的第一行，则这行空行必须删除。
|
||||
- 表格需要有表头描述，同一文档中相同类型表格的表头描述需要保持一致。
|
||||
|
||||
2. 表头规范
|
||||
```markdown
|
||||
| 姓名 | 年龄 | 职业 |
|
||||
|:-------|:-----|:-----|
|
||||
| 张三 | 25 | 程序员 |
|
||||
| 李四 | 30 | 设计师 |
|
||||
```
|
||||
|
||||
同一技术文档或产品手册中相同类型表格的表头描述需要保持一致。
|
||||
- 每个表格下都要空一行，空行的样式为正文。
|
||||
|
||||
【注意】对参数进行说明的表，应该统一表头描述，不要出现“参数说明”、“参数解释”、“参数含义”、“参数意义”等不同的描述。
|
||||
|
||||
3. 单元格内容规范
|
||||
|
||||
- 表格中的内容应该尽量简练，文字表述风格保持一致。避免长篇大段的说明，建议单元格中的内容所占行数不要超过 6 行。
|
||||
- 不出现空白的单元格。建议无内容单元格填写“无”或特定含义符号（如“/”）。若使用特定含义符号，需说明符号代表的意义。
|
||||
- 单元格内容避免重复。如果多个单元格中的内容相同，建议将内容复制或者采用多个单元格合并的方式，不要使用“同上”。
|
||||
|
||||
4. 表说明规范
|
||||
|
||||
表说明即表格之前或之后的一行表描述，可能带有序号或编号，主要是为了简要描述表格内容。
|
||||
|
||||
- 表说明采用名词词组形式。
|
||||
- 表说明简明扼要，长度不能超过表的宽度。
|
||||
- 同类表格的表说明在全文中风格保持统一。
|
||||
```markdown
|
||||
| 姓名 | 年龄 | 职业 |
|
||||
|:-------|:-----|:-----|
|
||||
| 张三 | 25 | 程序员 |
|
||||
| 李四 | 30 | 设计师 |
|
||||
□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□
|
||||
这是正文部分
|
||||
```
|
||||
|
||||
## 图形和图片
|
||||
|
||||
技术文档中插入图形与图片建议遵循以下规范。
|
||||
|
||||
- 必须使用清晰可辨的图形图片。
|
||||
- **必须使用清晰可辨的图形图片。**
|
||||
- 中文文档里图形图片上的文字建议都用中文，如果原图文字是其他语言，应该先做好图片本地化工作。
|
||||
- 文字建议使用**免费开源可商用字体**，以免引入法律风险。如不确定使用的字体是否能商用，可以在 [360 查字体](http://fonts.safe.360.cn/)网站中查证。
|
||||
- 同一文档内图形图片上的中文应该统一字体（如“思源黑体”），英文和数字也要统一字体（如“Times New Roman”）。
|
||||
- 文字建议使用**免费开源可商用字体**，以免引入法律风险。同一文档内图形图片上的中文应该统一字体（如思源黑体），英文和数字也要统一字体（如 Times New Roman）。
|
||||
- 图形图片中避免出现大段文字，描述性语言建议放到图外，用编号替代。
|
||||
- 图形图片中包含缩略语时，需要在图说明中对缩略语进行解释。
|
||||
- 图说明和图尽量保证在同一页中显示。
|
||||
- 图片的命名建议使用描述性的文字。
|
||||
- 插入图片时建议添加替代文本，从而改进文档的无障碍访问。例如，HTML 语法可以直接[添加 `alt` 属性](https://www.w3school.com.cn/html/html_images.asp)，Markdown 里使用[添加替代文本](https://markdown.com.cn/basic-syntax/images.html)，Microsoft Word 里使用[“编辑替换文字”功能](https://support.microsoft.com/zh-cn/office/向形状、图片、图表、smartart-图形或其它对象添加替换文字-44989b2a-903c-4d9a-b742-6a75b451c669)。
|
||||
- 插入图片时建议添加替代文本，从而改进文档的可访问性。
|
||||
|
||||
## 注意和说明
|
||||
```markdown
|
||||
|
||||
|
||||
注意和说明内容在技术文档中起强调作用。技术文档中使用注意和说明建议遵循以下规范。
|
||||
|
||||
- 根据提示内容的级别和分类使用不同的文字描述。例如，分类可以包括“危险”、“警告”、“小心”、“注意”、“说明”、“建议”、“举例”、“错误”等。
|
||||
- 注意和说明中不能包含表格和图形。
|
||||
- 注意和说明的内容不能过长，建议不要超过 4 行。
|
||||
- **说明**：图1. 这是一幅示例图片。其中的文字全部使用了中文，并且字体统一为思源黑体。对于图中的缩略语，我们在这里进行解释：XYZ代表的是...
|
||||
```
|
||||
|
||||
## 代码块和代码注释
|
||||
|
||||
技术文档中插入代码块建议遵循以下规范。
|
||||
- 如果代码块语言被支持，那么应该明确声明语言类型。
|
||||
|
||||
- 代码块前后必须加上一行空行。
|
||||
- 代码块要注意缩进。例如，当前代码块属于列表项下的内容，则要在该列表项的缩进基础上再缩进四格。
|
||||
- 如果前端支持，建议高亮代码块，方便阅读。
|
||||
- 如果前端支持，建议为代码块加上可供用户直接复制代码的按钮，提高文档易用性。
|
||||
````markdown
|
||||
```python
|
||||
# 这是一个 Python 示例
|
||||
print("Hello, World!")
|
||||
```
|
||||
````
|
||||
|
||||
代码注释一般出现在多行代码块中。技术文档中插入代码注释建议遵循以下规范。
|
||||
- 代码块中出现的长命令应当按逻辑进行换行，并且注明需要换行的地方。
|
||||
|
||||
- 一行注释不能太长，太长时应适当进行断句并切分到下一行。
|
||||
- 一行注释末尾建议加上标点符号，一般是句号；与下一行的内容承接时，用逗号。
|
||||
- 必须根据代码块中定义的语法选择相应的注释符，不能自创注释符。
|
||||
````markdown
|
||||
```bash
|
||||
# 在这个长命令中，我们使用 \ 来进行换行
|
||||
command --option1 --option2 \
|
||||
--option3 --option4 --option5
|
||||
```
|
||||
````
|
||||
|
||||
## 链接
|
||||
- 代码块中的命令，如需参数替换，应该清晰标注。
|
||||
|
||||
技术文档中的链接将用户引导至同一文档中的其他标题、其他相邻文档或外部站点。本节主要介绍在使用 Markdown 语言编写的技术文档中使用链接建议遵循的规范。
|
||||
````markdown
|
||||
```bash
|
||||
# 在这个命令中，<username> 需要被你的用户名替换
|
||||
ssh <username>@example.com
|
||||
```
|
||||
````
|
||||
|
||||
Markdown 中的链接格式示例：
|
||||
- 代码块中不应当出现警告或者错误信息，除非它们是文章需要表达的内容。
|
||||
|
||||
- 链至同一文档中的其他标题：`[产品架构](#产品架构)`
|
||||
- 链至其他相邻文档：`[产品架构](#产品架构)`
|
||||
- 链至外部站点：`[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/)`
|
||||
````markdown
|
||||
```python
|
||||
# 这个 Python 示例没有任何错误或警告
|
||||
def greet(name):
|
||||
print(f"Hello, {name}!")
|
||||
greet("World")
|
||||
```
|
||||
````
|
||||
|
||||
### 链接的描述
|
||||
- 代码注释需要使用英文，并且注释要简洁明了，且必须准确。
|
||||
|
||||
Markdown 链接中方括号 `[]` 里的内容为该链接的描述性文本。链接的描述需要符合以下规范。
|
||||
````markdown
|
||||
```python
|
||||
# Correct and concise comment: Print greeting
|
||||
print("Hello, World!")
|
||||
```
|
||||
````
|
||||
|
||||
- 链接描述必须能概括所链文档或页面的大致内容，这有利于搜索引擎优化。例如，链接描述可以是所链页面的标题。
|
||||
- 【错误示例】
|
||||
- 详情参见 `[trouble-shooting.md](trouble-shooting)`
|
||||
- 详情请点击`[这里](trouble-shooting)`
|
||||
- 【正确示例】
|
||||
- 关于以上配置项的更多细节，参见`[功能配置集](#功能配置集)`的相关配置项。
|
||||
- 详情参见`[故障诊断文档](trouble-shooting)`。
|
||||
- 同类型的链接描述应尽量统一风格。例如：同一文档内不宜多次出现“详情参见”、“详情参阅”、“具体见”、“具体请见”等表达相同意思的不同描述。
|
||||
- 如果代码块中的注释和文章内容重复，那么优先使用代码块中的注释，同时去掉文章中的内容。
|
||||
|
||||
### 链接的路径
|
||||
````markdown
|
||||
```python
|
||||
# This comment explains the following code block
|
||||
print("Hello, World!") # This line prints a greeting
|
||||
```
|
||||
````
|
||||
|
||||
Markdown 链接中圆括号 `()` 里的内容即为该链接的路径。链接的路径需要符合以下规范。
|
||||
## 链接和引用
|
||||
|
||||
- **如链至其他相邻文档，且链接的文档篇幅较长，建议链接至锚点**。链接至锚点即链接至某级标题处。Markdown 支持在链接路径的文件名后加“#标题名称”，即可以链接至该文件的特定标题处。
|
||||
- 链接和引用必须给出精确的位置信息。例如，如果你正在引用一个具体的 GitHub 代码行：
|
||||
|
||||
- 【示例】`[配置文件](#配置文件)`这个链接将链至 trouble-shooting.md 文件的“配置文件”标题下。
|
||||
```markdown
|
||||
看一下 [这个具体的代码行](https://github.com/user/repository/blob/master/file.py#L42) 来理解如何实现这个功能。
|
||||
```
|
||||
|
||||
- 链接路径应尽量统一风格。例如，链接至非外部站点时应统一使用相对路径或绝对路径，不建议混用相对路径和绝对路径。
|
||||
- 如果链接和引用的位置有更新，必须及时更新链接。
|
||||
|
||||
- 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验。
|
||||
```markdown
|
||||
由于最新的更新，参考 [新的代码实现](https://github.com/user/repository/blob/master/new_file.py#L50)。
|
||||
```
|
||||
|
||||
> 外部站点的含义：A 网站的文档中出现了一个 B 链接，如果 B 与 A 的域名或服务器不一样，则对于 A 网站的文档来说，B 链接为外部站点。例如：cloud.google.com 相对于 support.google.com 为内部站点；cloud.google.com 相对于 kubernetes.io 为外部站点。
|
||||
- 链接和引用中出现的代码，必须使用代码块包围。
|
||||
|
||||
- **如果必须将用户链至外部站点，建议在该外链后加上明显的标示，提醒用户该链接将前往外部站点。**
|
||||
````markdown
|
||||
参考以下代码实现：
|
||||
|
||||
> 由于不同网站的使用条款和隐私政策不同，用户使用当前站点，一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前，网站维护者有责任提醒用户当前的链接是去往外部站点，跳出去之后如果用户发生问题，不是当前站点的责任。
|
||||
```python
|
||||
def greet(name):
|
||||
```
|
||||
````
|
||||
|
||||
- 【示例一】如果前端能力足够，可以在外链后加上通用的外链 icon 效果，比如：[贡献者名单](https://github.com/yikeke/zh-style-guide/graphs/contributors)。
|
||||
- 【示例二】在 Markdown 中，可以简单在链接的路径后加上 `"点击前往外部站点"` 或者 `"点击前往 XXX 网站"`等信息，如 `[链接的描述](链接的路径 "前往外部链接的提示")`，即可在正常渲染下，实现鼠标悬停在超链接上时出现提示的效果。
|
||||
- 必须标注链接的类型，如文章、工具、命令等。
|
||||
|
||||
## 引用
|
||||
```markdown
|
||||
阅读这篇 [文章](https://example.com/article) 来更深入地了解这个主题。
|
||||
使用这个 [工具](https://example.com/tool) 来帮助你的开发工作。
|
||||
运行以下 [命令](https://example.com/command) 来配置你的环境。
|
||||
```
|
||||
|
||||
技术文档中使用引用建议遵循以下规范。
|
||||
- 每个文件的引用必须声明来源，使用全称，不要使用相对路径或者绝对路径。
|
||||
|
||||
- 当某内容在其他地方已经详细描述过、不适合在正文中再次介绍时，可以使用引用。
|
||||
- 对于必须引用但内容很少（少于 100 字）的情况，建议直接在该处重新描述一遍。
|
||||
- 必须保证引用的位置准确。
|
||||
```markdown
|
||||
引用自 [Python官方文档](https://docs.python.org/3/tutorial/index.html)，不是 `../tutorial/index.html` 或者 `/home/user/docs/tutorial/index.html`。
|
||||
```
|
||||
|
||||
技术文档中引用第三方内容建议遵循以下规范。
|
||||
- 不能使用会失效的链接。
|
||||
|
||||
- 引用他人的语句时，应注明出处。
|
||||
- 【示例】One man’s constant is another man’s variable. — Alan Perlis
|
||||
- 全篇转载时，应在全文开头显著位置注明作者和出处，并链接至原文。
|
||||
- 【示例】本文转载自 WikiQuote
|
||||
- 使用外部图片时，必须在图片下方或文末标明来源。
|
||||
- 【示例】本文部分图片来自 Wikipedia
|
||||
```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)。
|
||||
```
|
||||
|
||||
## 缩略语
|
||||
|
||||
中文技术文档中的缩略语有两种：汉语缩略语和英语缩略语。下文分别介绍了两者的概念、特点及使用规范。
|
||||
在编写中文技术文档时，我们常会用到两类缩略语：汉语缩略语和英语缩略语。
|
||||
|
||||
### 汉语缩略语
|
||||
|
||||
汉语缩略语是由较长的中文语词缩短省略而成的语词，如“人大”、“重启”、“停机”、“绑核”等。
|
||||
汉语缩略语是通过缩短和省略较长的中文词语来形成的新词。例如，「人大」是「人民大会堂」的缩略，而「重启」则是「重启动」的缩略。
|
||||
|
||||
由于汉语缩略语一般数量较少、含义明确，在技术文档中只要保证该缩略语通俗易懂、不造成歧义，原则上不限制使用次数。如果某词在文档中必须大量使用，但其缩略语不常见，建议在该词第一次出现时说明情况，提示读者下文中将以缩略语的形式称呼该词。
|
||||
**使用汉语缩略语时，我们要确保这些词在上下文中的含义清晰、准确，以避免产生歧义。**如果某个汉语缩略语并非大众常用或容易理解，我们在初次使用时应提供全称和相应的解释。例如，如果我们在文档中使用「绑核」作为「核心绑定」的缩略，我们需要在初次使用时指出：「本文将使用'绑核'作为'核心绑定'的缩略」。
|
||||
|
||||
### 英语缩略语
|
||||
|
||||
英语缩略语数量巨大、种类繁多，出现在中文技术文档中的主要有三种：首字母缩略词 (acronym)、字母词 (initialism) 和缩写词 (shortened word) 。三者的区别是：
|
||||
相较于汉语缩略语，英语缩略语种类繁多，数量众多。一般来说，它们分为三类：**首字母缩略词、字母词和缩写词。**
|
||||
|
||||
- 首字母缩略词：由每个词的首字母组成，以词的形式发音。
|
||||
- 【示例】NATO 代表 North Atlantic Treaty Organization
|
||||
- 字母词：也是由每个词的首字母组成，但按字母逐字发音。
|
||||
- 【示例】FBI 代表 Federal Bureau of Investigation
|
||||
- 缩写词：由较长的中文语词缩短省略而成的语词。
|
||||
- 【示例】App 代表 Application；demo 代表 demonstration
|
||||
- 首字母缩略词：这类缩略词是由每个单词的首字母组合而成，且作为一个单词发音。如「NATO」（North Atlantic Treaty Organization），我们读作 /'neɪtoʊ/，而**非逐字母发音。**
|
||||
|
||||
在技术文档中使用英语缩略语建议遵循以下规范。
|
||||
- 字母词：与首字母缩略词类似，也是由每个词的首字母组成，但是按字母逐一发音。例如，「FBI」（Federal Bureau of Investigation），我们会读作 /'efbi:'aɪ/，而**非作为一个单词发音。**
|
||||
|
||||
- 不建议在标题中解释英文缩略语，以免造成标题冗长。
|
||||
- 建议在正文中第一次出现缩略语的地方解释其完整含义。
|
||||
- 某词用缩略语进行代称时，必须在该词第一次出现时说明情况，提示读者下文中将以缩略语的形式称呼该词。
|
||||
- 禁止使用不规范的缩略语，例如，用“16c32g”表示“16 核、32 GB”；用“10w”表示 10 万。
|
||||
- 缩写词：直接将较长的词语进行缩短形成新词。例如，「App」是「Application」的缩写词，「demo」则是「demonstration」的缩写词。我们读作 /'æp/，而**非逐字母发音。**
|
||||
|
||||
在使用英语缩略语时，我们需要注意以下几点：
|
||||
|
||||
- 在标题中，避免对英文缩略语进行解释，以免使标题过长，影响阅读。
|
||||
|
||||
- 在正文中，首次出现的英文缩略语需要提供其完整形式和对应的解释。例如，如果我们首次使用「AI」，我们需要指出：「AI（Artificial Intelligence，人工智能）」。
|
||||
|
||||
- 当使用缩略语代指某词时，必须在该词首次出现时告知读者，下文将以缩略语的形式称呼该词。
|
||||
|
||||
- 不要使用非标准的或可能引起混淆的缩略语，例如，「16c32g」不能用来表示「16核、32GB」，「10w」也不能用来表示「10万」。
|
||||
|
||||
## 数字
|
||||
|
||||
在中文语境中，数字有两种形式：第一种是汉字数字，如“二”、“十”等；第二种是阿拉伯数字，如“2”、“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”事件 |
|
||||
| 现代社会生活中出现的事物、现象、事件，其名称的书写形式中包含阿拉伯数字，已经广泛使用而稳定下来 | 4G 手机、MP4 播放器、维生素 B12、「5·27」事件 |
|
||||
| 希望突出简洁醒目的表达效果时 | 北京时间 2020 年 10 月 1 日 12 点整 |
|
||||
|
||||
#### 选用汉字数字
|
||||
### 单位符号
|
||||
|
||||
| 适用场景 | 示例 |
|
||||
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| 数字连用表示的概数、含“几”的概数等 | 三四个月、一二十个、十五六岁、五六万套、五六十年前、几千、二十几、一百几十、几十万分之一 |
|
||||
| 干支纪年、农历月日、历史朝代纪年及其他传统上采用汉字形式的非公历纪年 | 腊月二十三、正月初五、八月十五中秋、秦文公四十四年、太平天国庚申十年九月二十三号、日本庆应三年、丙寅年十月十五日 |
|
||||
| 汉语中长期使用且已稳定下来的包含汉字数字形式的词语 | 星期五、四氧化三铁、一方面、不二法门、二八年华、二百五、八国联军、五四运动、万一、一旦、四书五经、七上八下、不管三七二十一、半斤八两、“一·二八”事变、“一·二九”运动 |
|
||||
| 希望突出庄重典雅的表达效果时 | 六方会谈（不写为“6 方会谈”）、十一届全国人大一次会议（不写为“11 届全国人大 1 次会议”） |
|
||||
- 汉字名称：建议用汉字名称代替单位符号。例如： `三米` 而不是 `3m`。
|
||||
|
||||
#### 选用阿拉伯数字和汉字数字均可
|
||||
- 间隔空格：数值和单位之间通常需要空一个半角空格，但有例外情况。例如： `3□kg`。
|
||||
|
||||
如果表达计量或编号所需要用到的数字个数不多，选择阿拉伯数字还是汉字数字在书写的简洁性及辨识的清晰性两方面没有明显差异时，两种形式均可使用。
|
||||
- 角度、摄氏度和百分号：角度、摄氏度和百分号的单位与数值之间不空格。例如： `45°`、 `20°C` 或 `50%`。
|
||||
|
||||
如下表所示，在不同场景下，下列两种形式均可使用：
|
||||
- 英尺符号和英寸符号：英尺符号和英寸符号与数值之间不空格。例如： `6'2"`。
|
||||
|
||||
| 阿拉伯数字形式 | 汉字数字形式 |
|
||||
| ----------------- | -------------------- |
|
||||
| 3 倍 | 三倍 |
|
||||
| 100 多个数据中心 | 一百多个数据中心 |
|
||||
| 20 余次 | 二十余次 |
|
||||
| 约 300 人 | 约三百人 |
|
||||
| 40 左右 | 四十左右 |
|
||||
| 第 40 页 | 第四十页 |
|
||||
| 第 9 天 | 第九天 |
|
||||
| 第 4 季度 | 第四季度 |
|
||||
| 共 128 位贡献者 | 共一百二十八位贡献者 |
|
||||
| 0.5 | 零点五 |
|
||||
| 1/3 | 三分之一 |
|
||||
| 公元前 8 世纪 | 公元前八世纪 |
|
||||
| 20 世纪 80 年代 | 二十世纪八十年代 |
|
||||
| 公元 278 年 | 公元二七八年 |
|
||||
| 1997 年 4 月 1 日 | 一九九七年四月一日 |
|
||||
| 下午 4 点 27 分 | 下午四点二十七分 |
|
||||
| 单位形式 | 示例 |
|
||||
| -------------------- | -------------- |
|
||||
| 汉字名称 | 三米 |
|
||||
| 间隔空格 | 3□kg |
|
||||
| 角度、摄氏度和百分号 | 45°、20°C、50% |
|
||||
| 英尺符号和英寸符号 | 6'2" |
|
||||
|
||||
#### 其他注意事项
|
||||
## 拼写
|
||||
|
||||
1. 在同一场景出现的数字，应遵循“同类别同形式”原则来选择数字的形式。
|
||||
中文技术文档既包含中文内容，也可能包含英文内容。因此，我们必须避免以下几种拼写错误。
|
||||
|
||||
如果两个数字的表达功能类别相同（比如都是表达年月日时间的数字），或者两个数字在上下文中所处的层级相同（比如文章目录中同级标题的编号），应选用相同的数字形式。反之，如果两个数字的表达功能不同，或所处层级不同，可以选用不同的形式。
|
||||
- 禁止简体中文和繁体中文的混用。
|
||||
|
||||
- 【示例一】2020 年 10 月 1 日 或者 二〇二〇年十月一日 （不写为“二〇二〇年 10 月 1 日”）
|
||||
- 【示例二】第一章 第二章……第十二章（不写为“第一章 第二章……第 12 章”）
|
||||
- 【示例三】第二章的下一级标题可以用阿拉伯数字编号：2.1、2.1.1、2.1.2、2.2……
|
||||
> 这款软件的颜色设计很独特，它的界面顏色是由用户自己选择的。❌
|
||||
>
|
||||
> 正确示例：这款软件的颜色设计很独特，它的界面颜色是由用户自己选择的。
|
||||
|
||||
2. 应避免相邻的两个阿拉伯数字造成歧义的情况。
|
||||
- 禁止出现中英文错别字。错别字包括错字和别字。
|
||||
|
||||
- 【示例一】高三三个班 或者 高三 3 个班（不写为“高 3 3 个班”）
|
||||
- 【示例二】高三 2 班 或者 高三 (2) 班（不写为“高 3 2 班”）
|
||||
> 这款软件使用 MySOL 数据库存储数据。❌
|
||||
>
|
||||
> 这款软件使用 MySQL 数据库存储数据。
|
||||
|
||||
3. 有法律效力的文件、公告文件或财务文件中可同时采用汉字数字和阿拉伯数字。
|
||||
### 英文的大小写形式
|
||||
|
||||
- 【示例一】2019 年 7 月保险账户结算日利率为万分之一点五七五零 (0.015750%)
|
||||
- 【示例二】35.5 元（35 元 5 角、三十五元五角或者叁拾伍元伍角）
|
||||
- 英文大小写形式不能写错。
|
||||
|
||||
### 阿拉伯数字的使用
|
||||
> 错误示例：用户可以在 mysql 数据库中创建新的表。❌
|
||||
>
|
||||
> 正确示例：用户可以在 MySQL 数据库中创建新的表。
|
||||
|
||||
技术文档中使用阿拉伯数字建议遵循如下规范。
|
||||
- 当中文句子中夹有英文单词或词组时，无论该英文单词或词组位于中文句子的开头、中间还是末尾，普通单词、词组必须小写；专有名词等在英文中必须大写的单词或词组，保留其大写形式。
|
||||
|
||||
#### 格式
|
||||
> 错误示例：在 SQL 语句中，你可以使用 "SELECT" 语句获取数据。❌
|
||||
>
|
||||
> 正确示例：在 SQL 语句中，你可以使用 "select" 语句获取数据。
|
||||
|
||||
书写格式上建议遵循如下字体、空格、换行规范。
|
||||
- 当中文句子中夹有完整的英文句子时，无论该英文句子位于中文句子的开头、中间还是末尾，其首字母均保留大写形式。
|
||||
|
||||
- 数字与英文字母一样，一律使用**半角形式**（即半个汉字位置），不得使用全角形式。
|
||||
- 【错误示例】每２分钟导入一个２５６ MB 的数据文件。
|
||||
- 【正确示例】每 2 分钟导入一个 256 MB 的数据文件。
|
||||
- 在不作任何后期排版处理的前提下，建议半角数字两旁各空一个空格。
|
||||
- 【错误示例】每2分钟导入一个256MB 的数据文件。
|
||||
- 【正确示例】每 2 分钟导入一个 256 MB 的数据文件。
|
||||
- 一个用阿拉伯数字书写的数值必须在同一行中，**不能断开移行**。
|
||||
> 错误示例：如需更多信息，请参阅 "in this chapter, we will learn how to create tables."❌
|
||||
>
|
||||
> 正确示例：如需更多信息，请参阅 "In this chapter, we will learn how to create tables."
|
||||
|
||||
#### 多位数值
|
||||
## 语法
|
||||
|
||||
技术文档中书写多位数值建议遵循如下规范。
|
||||
### 成分残缺
|
||||
|
||||
- 数值巨大的精确数字，建议使用“亿、万”作单位。如，10 亿 231 万 3245 人。
|
||||
- 数值为千位以上，建议添加半角逗号“,”作为分节符。
|
||||
- 多位整数从右到左分节，每三位一节，如 2,345,567,456。
|
||||
- 小数部分不分节，如 19,256,289.23456。
|
||||
- 四位以内的整数可以不分节，如 1289。
|
||||
在编写技术文档时，务必确保语句的成分完整。每个句子都应该有一个明确的主语和谓语，以及必要的宾语和定语。
|
||||
|
||||
#### 数值范围
|
||||
> 会话保持：在应用程序没有提供会话保持的功能下，HAProxy 可以提供该项功能。❌
|
||||
>
|
||||
> 会话保持：在应用程序没有提供会话保持功能的情况下，HAProxy 可以提供该项功能。
|
||||
|
||||
技术文档中书写数值范围建议遵循如下规范。
|
||||
### 搭配不当
|
||||
|
||||
- 在表示数值的范围时，可采用浪纹式连接号“～”或一字线连接号“—”。
|
||||
确保你的句子中使用的词汇是搭配恰当的。不正确的词汇搭配可能会让读者混淆，影响他们对你的文档的理解。
|
||||
|
||||
【示例】-36～-8 ℃、400—429 页、100—198 kg、12500～20000 元
|
||||
> HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，并仍然负责该项目的维护，该在开源社区提供免费和版本迭代。❌
|
||||
>
|
||||
> HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写，他现在仍然负责该项目的维护，并在开源社区免费提供版本迭代。
|
||||
|
||||
- 前后两个数值的附加符号或计量单位相同时，在**不造成歧义**的情况下，前一个数值的附加符号或计量单位可省略。
|
||||
### 倍数表达
|
||||
|
||||
【示例】9 亿～20 亿（可写为 9～20 亿）、13 万元～100 万元（可写为 13～100 万元）、64 MB～1024 MB（可写为 64～1024 MB）、15%～30%（可写为 15～30%）
|
||||
技术文档中表达倍数建议遵循以下规范。
|
||||
|
||||
#### 年月日
|
||||
- 数值的增加必须明确使用「增加了」或「增加到」，不能只使用「增加」。「了」表增量，「到」表定量。
|
||||
- 数值的减少必须明确使用「降低了」或「降低到」，不能只使用「降低」。「了」表增量，「到」表定量。
|
||||
- 不能用「降低 N 倍」或「减少 N 倍」的表示法，要用「降低百分之几」或「减少百分之几」。
|
||||
|
||||
技术文档中使用阿拉伯数字表示年月日，建议遵循如下规范。
|
||||
| 表述方式 | 示例 | 校验 |
|
||||
| -------- | -------------------------- | ---- |
|
||||
| 增加了 | 处理速度增加了两倍。 | ✔ |
|
||||
| 只用增加 | 处理速度增加两倍。 | ❌ |
|
||||
| 增加到 | 处理速度增加到两倍。 | ✔ |
|
||||
| 只用增加 | 处理速度增加两倍。 | ❌ |
|
||||
| 降低了 | 处理速度降低了五十百分点。 | ✔ |
|
||||
| 降低N倍 | 处理速度降低两倍。 | ❌ |
|
||||
|
||||
- 四位数字表示的年份不应简写为两位数字。如“2019 年”不应简写为“19 年”。
|
||||
- 年月日的表达顺序按照口语中年月日的自然顺序书写。如 2008 年 8 月 8 日、1997 年 4 月 1 日。
|
||||
- “年”“月”可用“-”替代，但年月日不完整时不能替代。如 2020-8-8、1997-4-1、8 月 8 日（不写为“8-8”）、2020 年 8 月（不写为“2020-8”）
|
||||
- 月和日为一位数时，可在数字前补“0”。如 2020-08-08、1997-04-01。
|
||||
### 成分多余
|
||||
|
||||
#### 时分秒
|
||||
避免在句子中使用不必要的词汇或短语，这可能会使句子变得冗长和复杂，影响其清晰度和可读性。
|
||||
|
||||
技术文档中使用阿拉伯数字表示时分秒，建议遵循如下规范。
|
||||
> 根据官方建议，目前稳定版本的 HAProxy 为稳定版 2.0 特性。❌
|
||||
>
|
||||
> 官方目前建议使用 HAProxy 稳定版本 2.0。
|
||||
|
||||
- 计时方式既可采用 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。但有几种例外：
|
||||
- 单位是角度、摄氏度或百分号时，数值和单位之间不空格。如：60°、37°C、100% 等。
|
||||
- 单位是英尺符号和英寸符号时，数值和单位之间不空格。如：4′5″ 表示 4 英尺 5 英寸。注意，英尺符号为 `′`（[U+2032 Prime](https://www.compart.com/en/unicode/U+2032)），英寸符号为 `″`（[U+2033 Double Prime](https://www.compart.com/en/unicode/U+2033)）。
|
||||
> 当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群并用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若 DM-master 可用节点数超过部署节点的半数，即可正常提供服务。❌
|
||||
>
|
||||
> 当部署多个 DM-master 节点时，所有 DM-master 节点将使用内部嵌入的 etcd 组成集群。该 DM-master 集群用于存储集群节点信息、任务配置等元数据，同时通过 etcd 选举出 leader 节点。该 leader 节点用于提供集群管理、数据迁移任务管理相关的各类服务。因此，若可用的 DM-master 节点数超过部署节点的半数，即可正常提供服务。
|
||||
|
||||
@ -1,100 +1,78 @@
|
||||
---
|
||||
id: 文档结构
|
||||
title: 文档结构
|
||||
description: 文档结构
|
||||
keywords:
|
||||
- 文档
|
||||
- 结构
|
||||
tags:
|
||||
- 标签
|
||||
sidebar_position: 3
|
||||
data: 2022年3月8日
|
||||
author: 7Wate
|
||||
date: 2023-06-26
|
||||
---
|
||||
|
||||
## 标题
|
||||
|
||||
标题在技术文档中的地位非常重要，文档工程师要设计合理的标题层级和标题描述，帮助读者理清整篇文档的逻辑，使文章结构一目了然。
|
||||
文档结构是技术文档的重要组成部分，一个良好的文档结构能有效帮助读者理解和掌握文档的逻辑和主题。以下是一些关于文档结构的关键要点。
|
||||
|
||||
### 标题的层级
|
||||
### 层级
|
||||
|
||||
技术文档中使用标题最多不超过四级。**标题从一级开始递增使用，禁止跳级使用**。例如：一级标题下面不能直接使用三级标题；二级标题下面不能直接使用四级标题。
|
||||
在技术文档中，我们通常使用的**标题层级最多不超过三级。**标题应该按照层级递增，禁止跳级使用。为了保持文档的整洁和一致，除非有特殊需要，否则不建议使用四级标题，可以选择使用列表代替四级标题。
|
||||
|
||||
- 一级标题：即文章标题
|
||||
- 二级标题：文章正文部分的标题
|
||||
- 三级标题：二级标题下面一级的小标题
|
||||
- 四级标题：三级标题下面一级的小标题
|
||||
```markdown
|
||||
# 文章主标题
|
||||
## 主要章节的标题
|
||||
### 子章节的标题
|
||||
#### 四级标题使用列表代替
|
||||
```
|
||||
|
||||
下图为在 Markdown 技术文档中使用标题的示例，左侧是编辑文字，右侧是预览效果：
|
||||
### 描述
|
||||
|
||||
|
||||
标题的描述应简洁明确，可以采用：名词词组、主题词+动词、动词+主题词、定语+主题词、介词+定语+主题词等形式。它们应能概括反映本章节的中心内容。为了保持标题的一致性，同级别的标题应尽量使用相同的结构。
|
||||
|
||||
为避免出现过于复杂的章节，若无特殊需要，不建议使用四级标题。如果三级标题下有并列性的内容，建议使用列表 (list) 代替四级标题。如下图中，若内容 A、B、C 的篇幅不长，则右侧的标题样式比左侧的标题样式要好。
|
||||
1. **名词词组：** 例如「数据结构」、「网络安全」等。
|
||||
2. **主题词+动词：** 这种形式更加动态，例如「电池充电」、「程序执行」等。
|
||||
3. **动词+主题词：** 这种形式可以清晰地指示一个操作或行动，例如「安装软件」、「编写代码」等。
|
||||
4. **定语+主题词：** 这种形式可以给出更多的描述性信息，例如「高效的算法」、「重要的更新」等。
|
||||
5. **介词+定语+主题词：** 这种形式更加详细，例如「对数据结构的理解」、「在网络安全中的防御」等。
|
||||
|
||||
|
||||
### 注意事项
|
||||
|
||||
### 标题的描述
|
||||
|
||||
技术文档中的标题包括但不限于以下几种描述：
|
||||
|
||||
- 名词词组，如“…概述”、“…背景”、“…原理”
|
||||
- 主题词+动词，如“A 工具安装”、“A 工具部署”、“A 工具配置”
|
||||
- 动词+主题词，如“配置 MySQL 数据库”
|
||||
- 定语+主题词，如“A 工具的安装”，“A 工具的架构”
|
||||
- 介词+定语+主题词，如“对机器配置的要求”
|
||||
|
||||
标题描述的设计并无严格的模板，只要遵循以下几个原则即可：
|
||||
|
||||
- 标题能够概括反映本章节的中心内容
|
||||
- 标题简洁扼要、涵义明确
|
||||
- 同级别的标题尽量使用相同的结构
|
||||
- 标题描述**操作任务**时建议使用“动词+主题词”结构，不建议使用名词词组
|
||||
|
||||
### 使用标题的注意事项
|
||||
|
||||
技术文档中使用标题主要有以下几个注意事项：
|
||||
|
||||
- 下级标题禁止重复上一级标题的内容
|
||||
- 不建议标题以标点符号（如句号或问号）结尾
|
||||
- 不建议在标题中解释缩略语
|
||||
- 标题与标题之间应该有引导介绍性的句子。例如，一级标题和二级标题之间应有引言内容，二级标题和三级标题之间应有正文内容
|
||||
- 标题要避免孤立编号（即同级标题只有一个），正文不要有孤立的三级标题和四级标题
|
||||
- 项目列表是最小编号单位，因此项目列表下禁止嵌套任何级别的标题
|
||||
1. **避免重复：**例如，如果一级标题是「数据结构」，那么二级标题应避免再次使用「数据结构」，而应该是更具体的主题，如「数组」、「链表」等。
|
||||
2. **避免使用标点：** 例如，不应该写成「数据结构：数组。」，而应该是「数据结构：数组」。
|
||||
3. **避免解释缩略语：** 例如，不应该写成「API（Application Programming Interface）」，而应该在正文中解释这个缩略语。
|
||||
4. **添加引导性句子：** 例如，在标题「数据结构」和「数组」之间，可以添加一句话：「接下来，我们将详细讨论数据结构中的一种重要类型——数组。」
|
||||
5. **避免孤立编号的标题：** 正文不要有孤立的三级和四级标题，每个标题都应该在上一级标题的基础上展开。例如，如果一个部分只有一个三级标题，那么它应该被升级为二级标题。
|
||||
6. **项目列表作为最小编号单位：** 不应在项目列表中嵌套任何级别的标题。例如，列表中的每一项都应该是一个完整的思想或概念，而不是一个需要进一步分解的主题。
|
||||
|
||||
## 段落
|
||||
|
||||
段落是正文部分的基本构成单元之一，由多个句子组成。段落写作要求如下：
|
||||
段落是正文部分的基本构成单元，由多个句子组成。**每个段落应只有一个主题或中心句子，并且中心句子建议放在段落的开头，对全段内容进行概述。段落长度建议在 50~250 字之间，避免超过 300 字。**为提高可读性，段落之间应设置适当的间距。同时，技术描述类主题应考虑先图表、后句子的原则，避免仅依赖段落陈述。
|
||||
|
||||
- 一个段落只能有一个主题，或一个中心句子。
|
||||
- 段落的中心句子建议放在段首，对全段内容进行概述。后面陈述的句子为核心句服务。
|
||||
- 一个段落的长度建议在 50～200 字之间，尽量不要超过 250 字。（Word 里统计字数）
|
||||
- 一个段落里避免只有一个句子。如果句子很长，要避免”**一逗到底**”的情况，合理断句。
|
||||
- 段落之间建议设置合适的间距，提高可读性。
|
||||
- 段落的句子语气应该使用陈述和肯定语气，避免使用感叹语气。
|
||||
- 技术文档的段落开头不建议缩进，顶格开始即可。
|
||||
- 对于技术描述类主题，应考虑先图表，后句子的原则，不要单一地使用段落来陈述主题。
|
||||
另外，**句子应避免过长，建议不超过100字。**使用简单句和并列句，避免复杂的复合句，可以适当地断句，防止句子过长。
|
||||
|
||||
## 句子
|
||||
### 示例
|
||||
|
||||
句子以句号结尾，句号表示句子意思已完成。句子写作要求如下：
|
||||
```markdown
|
||||
1. 数据结构简介
|
||||
|
||||
- 句子要避免使用长句。一个句子建议不超过 100 字。
|
||||
- 句子要使用简单句和并列句，避免使用复合句。
|
||||
- 善于断句，避免“一逗到底”的现象。
|
||||
数据结构是计算机科学中的一个核心概念（中心句子）。它是数据值、数据之间的关系、以及对数据进行操作的函数的组织和存储方式。数据结构可以直接或间接地影响程序的效率。在计算机编程中，选择最合适的数据结构对于编写高效的代码至关重要（此段落的长度约为50字）。
|
||||
|
||||
【错误示例】原因是 DM 需要保存同步的 binlog position 信息，但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，就会存储的是一个错误的 binlog position，在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。
|
||||
2. 数组和链表
|
||||
|
||||
【分析】以上句子为多个分句构成的复合句。“一逗到底”的情况增加了理解整体句群含义的难度。这种情况下，应该在适当的地方进行断句，并添加“这”、“其”等代词，合理切分句与句之间的逻辑。
|
||||
数组和链表是两种常见的数据结构（中心句子）。如图1所示，数组是一种线性数据结构，它包含一个或多个元素，每个元素都有一个与之相关联的索引。与此不同，链表由一系列节点组成，每个节点包含一个值和一个指向下一个节点的指针（此段落的长度约为60字，图表在句子之前，便于读者理解）。
|
||||
```
|
||||
|
||||
【修改建议】由于 DM 需要保存同步的 binlog position 信息，且 MySQL binlog position 官方定义使用 uint32 存储，因此超过 4G 部分的 binlog position 的 offset 值会溢出。这会导致存储的是一个错误的 binlog position。在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。
|
||||
```markdown
|
||||
数据结构是计算机科学中的一个核心概念。（简单句）
|
||||
|
||||
数据结构可以直接或间接地影响程序的效率，因此在编程中选择最合适的数据结构至关重要。（并列句，不超过100字）
|
||||
|
||||
数组是一种线性数据结构，包含一个或多个元素，每个元素都有一个与之相关联的索引；链表则由一系列节点组成，每个节点包含一个值和一个指向下一个节点的指针。（并列句，分句处理，避免过长）
|
||||
```
|
||||
|
||||
## 目录
|
||||
|
||||
文档目录可以**通过各级标题自动生成**，帮助用户快速浏览全文结构和定位章节。
|
||||
|
||||
对于一本技术手册而言，必须提供总目录（包含所有章节及附录）。如果是安装手册等还需要提供图目录、表目录。
|
||||
|
||||
发布在网页端的技术手册，两侧一般都配置有导航栏，包括**全手册导航栏**及**页内导航栏**。这两种导航栏相当于技术手册的**总目录**及**单篇文档目录**。
|
||||
|
||||
如下是 PingCAP 技术文档站的目录实现：
|
||||
文档目录是帮助读者快速浏览和定位章节的重要工具。通过各级标题，我们可以自动生成文档目录。例如，技术手册必须提供总目录，包含所有章节和附录。在网页端发布的技术手册，通常会有全手册导航栏和页内导航栏，相当于总目录和单篇文档目录。这需要根据使用的文档框架自定义文档的标题层级，以确保导航栏能正确显示。
|
||||
|
||||
|
||||
|
||||
注意：
|
||||
|
||||
在实际操作中，文档右侧导航栏能显示哪些[标题层级](https://zh-style-guide.readthedocs.io/zh_CN/latest/标题.html#id2)，由使用的文档框架决定。例如 [Docusaurus 框架](https://docusaurus.io/docs/en/navigation)，虽然正文中对标题级别没有限制，但在右侧导航栏只支持显示二级标题 (##) 和三级标题 (###)，一级标题 (#) 和四级标题 (####) 不会出现在右侧导航栏中。
|
||||
|
||||
因此，建议各公司**根据使用的文档框架自定义文档的标题层级**，如果右侧导航栏无法显示一级标题 (#)，则可以自定义文档中的一级标题为 ##，二级标题为 ###，以此类推。
|
||||
@ -1,14 +0,0 @@
|
||||
---
|
||||
id: 文档质量检查工具
|
||||
title: 文档质量检查工具
|
||||
sidebar_position: 8
|
||||
data: 2022年3月8日
|
||||
---
|
||||
一名成熟的文档工作者应该配置自己的文档编辑器，保证其能对文档自动进行拼写和语法检查。推荐以下几种对文档自动进行质量检查的工具。
|
||||
|
||||
Grammarly
|
||||
Visual Studio Code 插件
|
||||
Code Spell Checker
|
||||
Markdownlint
|
||||
LanguageTool
|
||||
Vale
|
||||
@ -1,314 +1,195 @@
|
||||
---
|
||||
id: 标点符号
|
||||
title: 标点符号
|
||||
description: 标点符号
|
||||
keywords:
|
||||
- 文档
|
||||
- 标点
|
||||
- 符号
|
||||
tags:
|
||||
- 文档
|
||||
sidebar_position: 5
|
||||
data: 2022年3月8日
|
||||
author: 7Wate
|
||||
date: 2023-06-26
|
||||
---
|
||||
|
||||
## 常用中文标点符号
|
||||
|
||||
技术文档中容易用错的标点符号主要有：句号、逗号、顿号、分号、冒号、引号、括号、书名号、连接号、破折号、省略号、感叹号、斜杠与反斜杠。下文介绍了它们的使用规范。
|
||||
### 句号「。」
|
||||
|
||||
### 句号
|
||||
句号用于标示一句话的结束。在 Markdown 中，句号的使用和平常无异。
|
||||
|
||||
句号的形式为“。”，表示陈述语气，用于句末停顿。
|
||||
> 这是一个句子。
|
||||
|
||||
句号表示一个句子的意思已经完整，技术文档中应善用句号切分语意，帮助用户理清逻辑。
|
||||
### 逗号「，」
|
||||
|
||||
- 【错误示例】原因是 DM 需要保存同步的 binlog position 信息，但是 MySQL binlog position 官方定义使用 uint32 存储，所以超过 4G 部分的 binlog position 的 offset 值会溢出，就会存储的是一个错误的 binlog position，在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。
|
||||
- 【正确示例】由于 DM 需要保存同步的 binlog position 信息，且 MySQL binlog position 官方定义使用 uint32 存储，因此超过 4G 部分的 binlog position 的 offset 值会溢出。这会导致存储的是一个错误的 binlog position。在重启 task 或者 dm-worker 后，需要使用该 binlog position 重新解析 binlog/relay log，进而出现上面的错误。
|
||||
逗号用于在句子中创建停顿，分隔句子的不同部分。
|
||||
|
||||
### 逗号
|
||||
> 我需要，苹果，香蕉，和橙子。
|
||||
|
||||
逗号的形式为“，”，表示句子内部的一般性停顿。
|
||||
### 顿号「、」
|
||||
|
||||
逗号使用最为普遍，但不能滥用。**技术文档中不要出现“一‘逗’到底”的错误，即整个段落除了段落结尾外，全部停顿都使用逗号。**
|
||||
顿号用于列举或枚举同类事物。
|
||||
|
||||
- 【错误示例】首先判断出错发生在 relay log 写入还是 binlog replication/syncer unit 同步（通过日志出错信息中的 component 信息即可判断），如果错误发生在 relay log 模块，binlog replication/syncer unit 保存的断点都是正确的情况，可以先停止任务，停止 DM-worker，手动调节 relay meta 的 binlog-position 到 4，重启 DM-worker 重新拉取 relay log ，relay log 写入正常后启动任务会自动从断点继续同步。
|
||||
- 【正确示例】首先通过日志出错信息中的 component 信息，判断是在 relay log 写入阶段还是 binlog replication/syncer unit 同步阶段出错。如果错误发生在 relay log 模块，且 binlog replication/syncer unit 保存的断点都正确，则可以先停止任务和 DM-worker，手动调节 relay meta 的 binlog-position 到 4，再重启 DM-worker 重新拉取 relay log。relay log 写入正常后启动任务会自动从断点继续同步。
|
||||
> 我需要苹果、香蕉、和橙子。
|
||||
|
||||
### 顿号
|
||||
### 分号「；」
|
||||
|
||||
顿号的形式为“、”，表示中文句子内部**两个及以上**并列成分之间的短暂停顿，这里的并列成分通常指**同类的单字、词语或短句**。
|
||||
分号用于连接两个相关的句子。
|
||||
|
||||
英文中没有顿号，常用逗号来表示并列词语的停顿。因此对于英汉技术翻译者而言，更应该注意顿号的使用场景。
|
||||
> 我喜欢苹果；我也喜欢香蕉。
|
||||
|
||||
顿号的常见误用场景：
|
||||
### 冒号「：」
|
||||
|
||||
| 错误示例 | 正确示例 | 解释 |
|
||||
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| 此操作会关闭 TiDB，Pump，TiKV，PD 服务，并清空 Pump，TiKV，PD 数据目录。 | 此操作会关闭 TiDB、Pump、TiKV 和 PD 服务，并清空 Pump、TiKV 和 PD 的数据目录 | TiDB、Pump、TiKV、PD 是并列词语，使用顿号作短暂停顿即可，不需要用逗号。 |
|
||||
| 多角度、多侧面地观察分析事物，全方位，透视性地进行报道。 | 多角度、多侧面地观察分析事物，全方位、透视性地进行报道。 | 逗号虽然也可表示并列，但其停顿时间较长，如果并列词语之间顿号误用为逗号，会使语句松散，不便于语义的表述和朗读。 |
|
||||
| 如何进一步增强政府的危机意识、增强政府应对突发事件的透明度，提高应对突发事件的能力，真正做到处变不惊、处置有序，需要完善有关的制度。 | 如何进一步增强政府的危机意识，增强政府应对突发事件的透明度，提高应对突发事件的能力，真正做到处变不惊、处置有序，需要完善有关的制度。 | “增强政府的危机意识”和“增强政府应对突发事件的透明度”是分句，分句之间停顿时间较长，不能用顿号，应改为逗号。 |
|
||||
| 我们学习茅盾先生，就应该像他那样，坚持为人民写作，深入社会实践，反映社会生活的创作原则，与时代同步、与人民同心。 | 我们学习茅盾先生，就应该像他那样，坚持为人民写作，深入社会实践，反映社会生活的创作原则，与时代同步，与人民同心。 | 顿号前后并非并列词语，而是分句，因此顿号要改为逗号。 |
|
||||
| 资源等级结构（一次、二次、三次资源）比例失调，学科、地区分布不均衡、重复率过高等问题。 | 资源等级结构（一次、二次、三次资源）比例失调，学科、地区分布不均衡，重复率过高等问题。 | 这里误用顿号后，“学科、地区分布不均衡”与“重复率过高”成了并列词语，造成句子歧义。因此，要把“均衡”后的顿号改为逗号，使句子成为两个分句组成的复句。 |
|
||||
| 在我们现代化建设面临人口、资源、环境的承受力趋向极限、以及国际竞争力更趋激烈的双重挑战的形势下，教育理应发挥促进社会、环境与经济可持续发展的功能。 | 在我们现代化建设面临人口、资源、环境的承受力趋向极限以及国际竞争力更趋激烈的双重挑战的形势下，教育理应发挥促进社会、环境与经济可持续发展的功能。 | 顿号的作用相当于“和”“跟”“及”“或者”等连词。如果并列词语较长，最后一项可用“和”“跟”“及”“或者”等连词连接，连词前可以加逗号。此时的逗号，不仅表示停顿，而且也是为了行文疏朗有间隔。但连词前不能使用顿号。因为在并列词语中，连词的作用等同于顿号。如果在连词前使用顿号，就等于连用了两个顿号。 |
|
||||
| 任何教学大纲、教学方法、或者评估方法的不同，都可能培养出创新的思维。 | 任何教学大纲、教学方法或者评估方法的不同，都可能培养出创新的思维。 | 同上 |
|
||||
| 通过 TiUP cluster 组件就可以进行日常的运维工作，包括部署、启动、关闭、销毁、弹性扩缩容、升级 TiDB 集群、管理 TiDB 集群参数。 | 通过 TiUP cluster 组件就可以进行日常的运维工作，包括部署、启动、关闭、销毁、弹性扩缩容、升级 TiDB 集群，以及管理 TiDB 集群参数。 | 有的并列词语内部又包含并列词语，形成多层次的并列词语。如果在多层次并列词语之间全用顿号，就使得并列词语之间的层次混乱，不利于理解。 |
|
||||
| 在二十世纪六、七十年代，有关跨国公司向发展中国家收取了过高的技术转移费和向发展中国家转移了大量不适合发展中国家适用的技术的指责不绝于耳。 | 在二十世纪六七十年代，有关跨国公司向发展中国家收取了过高的技术转移费和向发展中国家转移了大量不适合发展中国家适用的技术的指责不绝于耳。 | **相邻的两个数字并列连用表示概数，必须使用汉字，连用的两个数字之间不得用顿号‘、’隔开。**（来自《GB/T 15835―1995《出版物上数字用法的规定》》） |
|
||||
| 加强政府、企业、科研机构和学术团体的密切合作，以实现产、学、研的有机结合。 | 加强政府、企业、科研机构和学术团体的密切合作，以实现产学研的有机结合。 | **有些简短的并列词语各项之间的联系很紧密，没有停顿，已成为不可分的整体，其内部不用顿号，并已约定俗成。**如“马列主义”“中小学生”“字词句”“产学研”“酸甜苦辣”等。 |
|
||||
| 3、行政文明建设中的依法行政将直接推动我国依法治国方略的实现。 | 3. 行政文明建设中的依法行政将直接推动我国依法治国方略的实现。 | 阿拉伯数字作为序数词，如“1”后用点号而不用顿号；汉字“一”后用顿号，“第一”后面用逗号。这些是约定俗成的用法。 |
|
||||
| - “日”、“月”构成“明”字。 - 店里挂着“顾客就是上帝”、“质量就是生命”等横幅。 - 《红楼梦》、《三国演义》、《西游记》、《水浒传》，是我国长篇小说的四大名著。 - 李白的“白发三千丈”（《秋浦歌》）“朝如青丝暮成雪”（《将进酒》）都是脍炙人口的诗句。 | **标有引号的并列成分之间、标有书名号的并列成分之间通常不用顿号。**若有其他成分插在并列的引号之间或并列的书名号之间（如引语或书名号之后还有括注），宜用顿号。 | - “日”“月”构成“明”字。 - 店里挂着“顾客就是上帝”“质量就是生命”等横幅。 - 《红楼梦》《三国演义》《西游记》《水浒传》，是我国长篇小说的四大名著。 - 李白的“白发三千丈”（《秋浦歌》）、“朝如青丝暮成雪”（《将进酒》）都是脍炙人口的诗句。 |
|
||||
| - 我走之后，你要不断进步、识字、生产。 - 这个故事讲得美丽、动人。 | - 我走之后，你要不断进步，识字，生产。 - 这个故事讲得美丽，动人。 | **并列的谓语，补语之间不用顿号，用逗号。** |
|
||||
冒号用于引出说明或解释，或引出直接引语。
|
||||
|
||||
以上规范来自 [8 例顿号误用解析 - 中国编辑校对网](http://www.bianjiao.net/page139?article_id=149&pagenum=all) 以及[顿号（标点符号）- 百度百科](https://baike.baidu.com/item/顿号/998522) 等。
|
||||
> 注：这是一句解释性的话。
|
||||
|
||||
### 分号
|
||||
### 引号「“ ”，‘ ’」
|
||||
|
||||
分号的形式为“；”，表示复句内部并列分句之间的停顿。**一般情况下，并列分句有三句或超过三句时，建议使用分号表示停顿。**
|
||||
引号用于引用别人的言论。
|
||||
|
||||
【示例】Placement Driver（简称 PD）是整个集群的管理模块，其主要工作有三个：一是存储集群的元信息（某个 Key 存储在哪个 TiKV 节点）；二是对 TiKV 集群进行调度和负载均衡（如数据的迁移、Raft group leader 的迁移等）；三是分配全局唯一且递增的事务 ID。
|
||||
> 他说：“我喜欢你。”
|
||||
|
||||
### 冒号
|
||||
### 括号「（）」
|
||||
|
||||
冒号的形式为“：”。在技术文档中常用在需要解释的词语后边，表示引出解释和说明。
|
||||
括号用于添加解释，注释，或者附加的信息。
|
||||
|
||||
冒号在技术文档中常用来引出列表。
|
||||
> 我喜欢吃水果（如苹果，香蕉，橙子）。
|
||||
|
||||
【示例】冯·诺依曼体系计算机的硬件系统分为五个部分：
|
||||
### 书名号「《》」
|
||||
|
||||
- 运算器
|
||||
- 控制器
|
||||
- 存储器
|
||||
- 输入设备
|
||||
- 输出设备
|
||||
书名号用于标注书籍，报纸，电影等作品的标题。
|
||||
|
||||
一个句子内建议不要连续套用冒号。
|
||||
> 我最近在读《哈利·波特》。
|
||||
|
||||
- 【错误示例】计数系统：逻辑表示：1，计数器加一；0，计数器不变。
|
||||
- 【正确示例】计数系统：1 表示计数器加一，0 表示计数器不变。
|
||||
### 连接号「-」
|
||||
|
||||
### 引号
|
||||
连接号用于连接两个有直接关联的词语。
|
||||
|
||||
引号分为直角引号和弯引号。直角引号为「」，弯引号有双引号和单引号两种形式。一般而言，技术文档中可以使用直角引号或弯引号，但**必须保证所有文档的统一，禁止混用**。
|
||||
> 中美-贸易
|
||||
|
||||
本节只讨论弯引号使用的一些规范，下文中使用的“引号”均表示“弯引号”。
|
||||
### 破折号「——」
|
||||
|
||||
- 引号内套用引号时，外面一层用双引号，里面一层用单引号。
|
||||
- 技术文档出现报错信息、特定操作或名称、缩略语提示、特殊名词、引用文档的节选等时，建议使用引号。
|
||||
- 【正确示例一】启动集群或者升级集群过程中出现”Timeout when waiting for search string 200 OK”是什么原因？
|
||||
- 【正确示例二】Sysbench 按照“建表->插入数据->创建索引”的顺序导入数据。
|
||||
- 【正确示例三】如果 `tidb-lightning` 曾经异常退出，集群可能仍留在“导入模式” (import mode)，不适合在生产环境工作。此时需要强制切换回“普通模式” (normal mode)。
|
||||
- 【正确示例四】作为 NewSQL 数据库，TiDB 兼顾了传统关系型数据库的优秀特性以及 NoSQL 数据库可扩展性，以及跨数据中心（下文简称“中心”）场景下的高可用。
|
||||
- 【正确示例五】以下操作可能会形成一个“关系环”。
|
||||
- 技术文档的正文中若涉及特定参数名称、字段名、界面字段等，建议使用引号（也可使用反引号）包裹。
|
||||
- 【正确示例一】在参数表中规定了 TMN 接口与支持这些接口的物理构件的关系，其中“M”表示必备，“O”表示可选。
|
||||
- 【正确示例二】具体命令请参见《Quidway S8016 路由交换机安装手册》中“1.2.1 安装步骤”的内容。
|
||||
- 【正确示例三】请设置如下三个参数：“Card Number”、“Password”、“Discount Rate”。
|
||||
破折号表示转折，解释，或者暂停。
|
||||
|
||||
### 括号
|
||||
> 我喜欢吃水果——尤其是苹果。
|
||||
|
||||
括号的常用形式包括圆括号`()`、方括号`[ ]`、方头括号`【】`、尖括号`<>`（也称单书名号）以及花括号`{}`。其中技术文档中常用的是圆括号、方括号以及尖括号。
|
||||
### 省略号「……」
|
||||
|
||||
中文文档中一个词语或句子后紧跟的注释性文字，用圆括号进行注解。注释句子里某些词语时，圆括号放在被注释词语之后；注释整个句子时，圆括号放在句末标点之后。
|
||||
省略号表示语句的不连续。
|
||||
|
||||
- 【正确示例一】TiDB 使用周期性运行的 GC（Garbage Collection，垃圾回收）来进行清理。
|
||||
- 【正确示例二】需要编辑配置文件以调整参数的值。（该方式不推荐使用）
|
||||
> 等待……
|
||||
|
||||
一般来说，方括号和尖括号在技术文档中有以下几种特定用法。
|
||||
### 感叹号「！」
|
||||
|
||||
- 方括号“[ ]”表示窗口名、菜单名等，如“弹出[新建任务]窗口”、“[显示/外观/全屏]多级菜单”。
|
||||
- 带尖括号“< >”表示按钮名、键名等，如“点击<取消>按钮”、“`<Tab>` 表示制表键”。
|
||||
感叹号用于标识感叹或者强烈的情绪。
|
||||
|
||||
### 书名号
|
||||
> 太好了！
|
||||
|
||||
书名号的形式为“《》”。书籍名、报刊名等名称需要用书名号标示。英文手册名称用中文双引号或斜体表示，不用书名号标示。
|
||||
### 斜杠「/」
|
||||
|
||||
- 【示例一】《小王子》这本书有很多种语言版本。
|
||||
- 【示例二】详情见“TiDB-Lightning 表库过滤”一文。
|
||||
在 Markdown 中，斜杠被用作转义字符，表示接下来的字符应被解析为文字，而非 Markdown 语法。
|
||||
|
||||
书名号中的文档名称建议使用全称，不使用简称。
|
||||
> 我\*喜欢\*你。
|
||||
>
|
||||
> 输出为：我*喜欢*你。
|
||||
|
||||
- 【错误示例】具体操作请参见《表库过滤》。
|
||||
- 【正确示例】具体操作请参见《TiDB Lightning 表库过滤》。
|
||||
### 反斜杠「\」
|
||||
|
||||
### 连接号
|
||||
在 Markdown 中，反斜杠主要用作转义字符。
|
||||
|
||||
连接号表示某些相关联成分的连接关系。连接号的常见形式包括一字线“—”（占一个汉字的宽度）、短横线“-”（占半个汉字的宽度）和浪纹线“～”（占一个汉字的宽度）。
|
||||
> \\\ 在 Markdown 中会输出一个斜杠：\。
|
||||
|
||||
几种连接号的作用及用法示例如下表所示。
|
||||
### 反引号「`」
|
||||
|
||||
| 符号 | 用法举例 |
|
||||
| --------- | ------------------------------------------------------------ |
|
||||
| 一字线 — | - 标示时间起止、空间起止或走向、序数起止等，如鲁迅（1881—1936）、2016—2020 年、1—3 月、北京—上海特快列车、秦岭—淮河线、13—15 号楼、第 50—100 条 - 在标准编号中连接顺序号与年号，如 GB/T 15835—2011 《出版物上数字用法》 |
|
||||
| 短横线 - | - 在电话号码、门牌号、图表编号、阿拉伯数字年月日等各种复合名词中起连接作用，如学院路 15 号 2-1-201 室、图 2-1、表 3-4、2020-09-30、吐鲁番-哈密盆地 - 在外来语内部成分中起连接作用，如让-雅各·卢梭、盎格鲁-撒克逊人 - 表示某些产品的名称和型号，如 GC-50 型号设备 |
|
||||
| 浪纹线 ～ | 标示数值范围：1～3 g、2～4 米、3～7 年内 |
|
||||
在 Markdown 中，反引号用于创建 `inline` 代码块。
|
||||
|
||||
> 粗略记忆方式：表示起止用一字线（—），表示范围用浪纹线（～），复合名词用短横线（-）。
|
||||
|
||||
### 破折号
|
||||
|
||||
破折号的形式为“——”，占两个汉字的宽度。技术文档中破折号常用于引出注释和说明部分。
|
||||
|
||||
【示例】于是新的数据库概念——NewSQL 数据库应运而生。
|
||||
|
||||
破折号前后不空格。
|
||||
|
||||
- 【错误示例】于是新的数据库概念 —— NewSQL 数据库应运而生。
|
||||
- 【正确示例】于是新的数据库概念——NewSQL 数据库应运而生。
|
||||
|
||||
### 省略号
|
||||
|
||||
中文省略号的形式为“……”，有六个小圆点，占两个汉字的宽度。一般而言，中文语境中禁止使用英文省略号，即三个小圆点“…”（占一个汉字的宽度），必须使用六个小圆点“……”。
|
||||
|
||||
省略号主要在以下两种场景中使用。
|
||||
|
||||
- 引文的省略，用省略号标明。
|
||||
|
||||
【示例】中文写作规范中要求：“句号常用于陈述句末尾的停顿。在产品资料中常用于简单句和复合句的结尾，表示句子意思已完整……”
|
||||
|
||||
- 列举的省略，用省略号标明。
|
||||
|
||||
【示例】分支选择支持所有类型的分区表，无论是 range 分区或是 hash 分区等。对于 hash 分区，如果没有指定分区名，会自动使用 `p0`、`p1`、`p2`、……、或 `pN-1` 作为分区名。
|
||||
|
||||
### 感叹号
|
||||
|
||||
技术文档中使用感叹号建议遵循以下规范。
|
||||
|
||||
- 尽量使用平静的语气叙述，避免使用感叹号。
|
||||
- 禁止多个感叹号连用，比如“！！”等。
|
||||
|
||||
### 斜杠与反斜杠
|
||||
|
||||
斜杠（slash 或 forward slash）的符号是“/”，表示分隔符。反斜杠 (backslash) 的符号是“\”，表示转义字符。反斜杠一般只出现在代码中，因此本节主要讨论斜杠的使用。
|
||||
|
||||
斜杠有如下几种用法。
|
||||
|
||||
- 表示除法，如 120/60 = 2
|
||||
- 表示单位（除法的变形），如 60 km/h
|
||||
- 表示“或”，如他/她。注意：如果需要表示多个并列项，不建议使用“/”连接，建议使用顿号连接。
|
||||
- 【错误示例】高可用是 TiDB 的另一大特点，TiDB/TiKV/PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。
|
||||
- 【正确示例】高可用是 TiDB 的另一大特点，TiDB、TiKV 和 PD 这三个组件都能容忍部分实例失效，不影响整个集群的可用性。
|
||||
|
||||
斜杠的两旁不建议加空格。
|
||||
|
||||
- 【错误示例】do / ignore 规则
|
||||
- 【正确示例】do/ignore 规则
|
||||
|
||||
### 反引号
|
||||
|
||||
> 注：本节只讨论出现在 Markdown 文档中的反引号情况。
|
||||
|
||||
反引号 (backtick) 的符号是“`”，一般在英文输入法下由键盘左上角 Tab 键上方的按键键入。
|
||||
|
||||
反引号有如下两种用法。
|
||||
|
||||
| 用法种类 | 单个反引号包裹单行元素 | 三个反引号包裹多行元素 |
|
||||
| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| 作用 | 强调包裹的部分，与正文内容区分 | - 便于展示多行代码 - 强调包裹的部分，与正文内容区分 - 在 Markdown 语法中，前面的 ``` 后若指明代码块中的语法，可高亮代码块 |
|
||||
| 示例 | ``time_zone` 的默认值是 `System`` | <三个反引号> create table t (ts timestamp, dt datetime); SELECT * FROM t1; <三个反引号> |
|
||||
| 适用情况 | 以下元素需要使用单个反引号包裹： - 变量名 - 变量的值 - 语法名称 - 命令或代码 - 配置项名 - 字段名 - 其他需要强调的名称，如文件名、表名、列名、库名、数据类型名称等 | 以下元素需要使用三个反引号包裹： - 多行代码块（多行 SQL 语句、多行 bash 命令等） - 代码执行结果 - 配置文件中的多行配置 |
|
||||
> \`print('Hello, World!')\` 在 Markdown 中会输出一个 inline 代码块：`print('Hello, World!')`。
|
||||
|
||||
## 中文标点使用
|
||||
|
||||
使用中文标点符号建议遵循以下规范。
|
||||
使用中文标点符号时，推荐遵循以下规则。
|
||||
|
||||
- **中文语境下的标点符号一律使用全角形式（即中文输入法下的标点符号）**，不得使用半角形式（即英文输入法下的标点符号）。
|
||||
- 在中文语境下，**标点符号应使用全角形式（即中文输入法下的标点符号）**，不能使用半角形式（即英文输入法下的标点符号）。
|
||||
|
||||
- **中文全角标点符号两旁禁止空半角空格**。示例：
|
||||
- 中文全角标点符号两侧不应该有半角空格。
|
||||
|
||||
- 【错误示例】如果 CPU 设有限额 （从 K8S 指定的上限） ，则需要手动调整。
|
||||
- 【正确示例】如果 CPU 设有限额（从 K8S 指定的上限），则需要手动调整。
|
||||
> 如果 CPU 设有限额□（从 K8S 指定的上限）□，则需要手动调整。❌
|
||||
>
|
||||
> 如果 CPU 设有限额（从 K8S 指定的上限），则需要手动调整。
|
||||
|
||||
- 句号、问号、叹号、逗号、顿号、分号、冒号、结束引号、结束括号等标点不能出现在一行的开头。
|
||||
- 句号、问号、叹号、逗号、顿号、分号、冒号、结束引号、结束括号等标点不应出现在一行的开头。
|
||||
|
||||
- 【错误示例】
|
||||
> 排版时注意某些
|
||||
> 符号不能在行首
|
||||
> ，别弄错了。❌
|
||||
>
|
||||
> 排版时注意某些
|
||||
> 符号不能在行首，
|
||||
> 别弄错了。
|
||||
|
||||
```
|
||||
排版时注意某些
|
||||
符号不能在行首
|
||||
，别弄错了。
|
||||
```
|
||||
- 开始引号、开始括号、开始双书名号等标点不应出现在一行的末尾。
|
||||
|
||||
- 【正确示例】
|
||||
> 她对我们说：“
|
||||
> 这书太赞了。”❌
|
||||
>
|
||||
> Copy code她对我们说：
|
||||
> “这书太赞了。”
|
||||
|
||||
```
|
||||
排版时注意某些
|
||||
符号不能在行首，
|
||||
别弄错了。
|
||||
```
|
||||
## 中英文混用时的标点符号用法
|
||||
|
||||
- 开始引号、开始括号、开始双书名号等标点不能出现在一行的结尾。
|
||||
在中文技术文档中，可能会出现英文，此时可能会使用全角形式的中文标点和半角形式的英文标点。在中英文混用时，需特别注意标点符号的使用。
|
||||
|
||||
- 【错误示例】
|
||||
|
||||
```
|
||||
她对我们说：“
|
||||
这书太赞了。”
|
||||
```
|
||||
|
||||
- 【正确示例】
|
||||
|
||||
```
|
||||
她对我们说：
|
||||
“这书太赞了。”
|
||||
```
|
||||
|
||||
## 中英文混用时标点符号用法
|
||||
|
||||
中文技术文档中有时会出现英文，此时，不仅会使用全角形式的中文标点，也可能使用半角形式的英文标点，因此在中英文混用时应着重注意标点符号的用法。
|
||||
|
||||
本节介绍中英文交接处使用标点符号的建议规范。
|
||||
这部分介绍在中英文交接处使用标点符号的规则。
|
||||
|
||||
### 根本原则
|
||||
|
||||
中文技术文档主要服务的是中文文本，应该**以中文标点符号为主**，以英文标点符号为辅。
|
||||
中文技术文档**主要针对中文文本，应以中文标点符号为主，英文标点符号为辅。**
|
||||
|
||||
### 基本规范
|
||||
|
||||
1. 中文句子内夹用英文单词或词组时：
|
||||
- 夹用的英文单词或词组可不用中文引号包裹。
|
||||
- **如果夹用的英文单词或词组本身带有英文标点，保留其英文标点**。
|
||||
- 中文句子句末均以中文标点符号结尾。
|
||||
2. 中文句子内夹用英文句子时：
|
||||
- 用中文引号包裹引用该英文句子。
|
||||
- **如果夹用的英文句子本身带有英文标点，保留其英文标点**。
|
||||
- 中文句子句末均以中文标点符号结尾。
|
||||
1. 在中文句子中使用英文单词或词组时：
|
||||
- 使用的英文单词或词组不需要用中文引号包围。
|
||||
- 如果使用的英文单词或词组本身有英文标点，保留其英文标点。
|
||||
- 中文句子的末尾应使用中文标点符号。
|
||||
2. 在中文句子中使用英文句子时：
|
||||
- 应用中文引号包围英文句子。
|
||||
- 如果英文句子本身有英文标点，保留其英文标点。
|
||||
- 中文句子的末尾应使用中文标点符号。
|
||||
|
||||
基于上面的基本规范，下表给出不同标点符号用法的例句：
|
||||
|
||||
| 标点符号 | 【中文句子内夹用英文单词或词组时】标点用法例句 | 【中文句子内夹用英文句子时】标点用法例句 |
|
||||
| 标点符号 | 中文句子内夹用英文单词或词组时 | 中文句子内夹用英文句子时 |
|
||||
| -------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| 句号 | - change 和 transform 意义不同。 - 建议叫上 Jane。 | - “I like you.（我喜欢你。）”与“I love you.（我爱你。）”的份量不一样。 - 他说的是“Jane, you can do it.”。 |
|
||||
| 句号 | change 和 transform 意义不同。 | I like you.（我喜欢你。） |
|
||||
| 逗号 | 这个数据库的官方描述是“open-source, distributed SQL database”。 | 他们的官方文档上写着“Try it out, and you will get a 10% discount.”。 |
|
||||
| 问号 | distributed SQL 在这里是什么意思？ | 他伸出手说“Need a hand?”，这句话的意思是“Do you need help?”？ |
|
||||
| 问号 | distributed SQL 在这里是什么意思？ | 他伸出手说“Need a hand?”，这句话的含义是“你需要帮助吗？”？ |
|
||||
| 叹号 | 不要总是对女孩说“Pretty!”！ | 他站在那，感叹了句“What a beautiful scene!”。 |
|
||||
| 顿号 | be 动词包括 is、are、were、was 等。 | “He is man.”、“He is a man.”和“He is the man”的区别是什么？ |
|
||||
| 顿号 | be 动词包括 is、are、were、was 等。 | “He is man.”、“He is a man.”和“He is the man。”三者的含义有何区别？ |
|
||||
| 分号 | 如果想表示更礼貌的语气，用 might；反之，用 may。 | 官方文档上说“To deploy the database, use the TiUP tool; to migrate data, use the DM tool.”。 |
|
||||
| 冒号 | - 官网有个首页按钮失效了：Newsletter。 - TiDB: The Future of Databases 是一篇主题分享博客。 | - 文档站的右上角写着：Try it now。 - Bilibili: How We Use a Distributed SQL Database 是一篇案例分享。 |
|
||||
| 引号 | 将来时态一般由“will + 动词原形”组成。 | 这篇文章里有句话比较难理解：“The saint said, 'Follow your fear.'”。 |
|
||||
| 冒号 | 官网有个首页按钮失效了：Newsletter。 | 文档站的右上角写着：Try it now。 |
|
||||
| 引号 | 将来时态通常由“will + 动词原形”组成。 | 这篇文章里有句话比较难理解：“The saint said, 'Follow your fear.'”。 |
|
||||
| 破折号 | 这个符号表示禁止——stop。 | “Well—emm, I don't know how to say—but I hope you can understand my position.”他纠结地说。 |
|
||||
| 省略号 | 使用 so...that... 句型表示结果，意思是“如此……以致……”。 | “I don't know how to say this...”的意思是“我不知道该怎么说了……”。 |
|
||||
|
||||
### 补充规范
|
||||
|
||||
除了两条基本规范外，本节介绍一些补充规范。
|
||||
|
||||
#### 英文标题或引文中的结尾符号
|
||||
|
||||
- **英文标题或引文中的结尾问号必须保留**
|
||||
- 【示例一】这篇文档的标题“How to Migrate Data from MySQL?”可以改为“How Do You Migrate Data from MySQL?”。
|
||||
- 【示例二】这个推文的第一句“Why do you migrate data from MySQL?”问得不够清楚。
|
||||
- **英文标题或引文中的结尾叹号必须保留**
|
||||
- 【示例一】“A little book of language!”一文受到了很多好评。
|
||||
- 【示例二】“加勒比海盗”的电影中的海盗总是说“Aye! Aye!”。
|
||||
| 省略号 | 使用 so...that... 句型表示结果，意思是“如此……以至于……”。 | “I don't know how to say this...”的含义是“我不知道该怎么说了……”。 |
|
||||
|
||||
#### 中英文括号的使用
|
||||
|
||||
中英文混用时使用括号**建议**遵循以下规范。
|
||||
- 括号里全为英文时建议使用半角括号，并在括号前后各空一个半角空格，括号和括号内的英文之间不需要空格。
|
||||
|
||||
- **括号里全为英文时**建议使用半角括号，并在括号前后各空一个半角空格，括号和括号内的英文之间不需要空格。
|
||||
- 【错误示例一】数据定义语言（DDL）是一种……（使用了全角括号）
|
||||
- 【错误示例二】数据定义语言(DDL)是一种……（半角括号前后未空格）
|
||||
- 【错误示例三】数据定义语言 ( DDL ) 是一种……（半角括号和半角括号内的英文之间空了一格）
|
||||
- 【正确示例】数据定义语言 (DDL) 是一种……
|
||||
- **括号里既有中文又有英文（即只要括号内包含任何中文）时**建议使用全角括号，括号前后不空格。
|
||||
- 【错误示例】斜杠 (slash 或 forward slash) 和反斜杠 (backslash) 是两种符号。
|
||||
- 【正确示例】斜杠（slash 或 forward slash）和反斜杠 (backslash) 是两种符号。
|
||||
> 数据定义语言（DDL）是一种……（使用了全角括号）❌
|
||||
> 数据定义语言(DDL)是一种……（半角括号前后未空格）❌
|
||||
> 数据定义语言□(□DDL□)□是一种……（半角括号和半角括号内的英文之间空了一格）❌
|
||||
>
|
||||
> 正确示例：数据定义语言□(DDL)□是一种……
|
||||
|
||||
- 括号里既有中文又有英文（即只要括号内包含任何中文）时建议使用全角括号，括号前后不空格。
|
||||
|
||||
> 斜杠 (slash 或 forward slash) 和反斜杠 (backslash) 是两种符号。❌
|
||||
>
|
||||
> 斜杠（slash 或 forward slash）和反斜杠 (backslash) 是两种符号。
|
||||
|
||||
#### 英文书籍、报刊、标题的引用方法
|
||||
|
||||
- 中文句子中夹用英文书籍或报刊名时，不能使用中文书名号《》，而应使用斜体字表示，如果无法使用斜体字，建议使用中文引号包裹引用。
|
||||
|
||||
- 英文文章的标题用中文引号包裹引用。
|
||||
|
||||
【示例】*New York Times* 发布了一篇新文章，标题是“Cloud is Eating the World”。
|
||||
> *New York Times* 发布了一篇新文章，标题是“Cloud is Eating the World”。
|
||||
|
||||
@ -1,53 +1,45 @@
|
||||
---
|
||||
id: 简介
|
||||
title: 简介
|
||||
description: 中文文档写作指南简介
|
||||
keywords:
|
||||
- 中文
|
||||
- 文档
|
||||
- 写作指南
|
||||
tags:
|
||||
- 文档
|
||||
sidebar_position: 1
|
||||
data: 2022年3月8日
|
||||
author: 7Wate
|
||||
date: 2023-06-26
|
||||
---
|
||||
|
||||
本指南规范了一种中文写作风格，主要用于技术文档的编写。素材来源于互联网，为各家中文文案风格指南的综合，旨在对中文技术文档的**语言风格、结构样式、内容元素、标点符号、格式排版**等方面给出参考规范。
|
||||
## 引言
|
||||
|
||||
> **引用者注：**
|
||||
>
|
||||
> 本篇系列文档引用自 yikeke 的开源项目《[中文技术文档写作风格指南](https://github.com/yikeke/zh-style-guide)》
|
||||
>
|
||||
> 本人进行了**二次修改**便于自己使用，**感谢原作者的开源奉献！**
|
||||
>
|
||||
> **作者注：**
|
||||
>
|
||||
> - 本指南只提供参考规范，不提供权威标准。一些规范在业界并无定论，争议点作者会以建议形式给出。
|
||||
> - 本指南欢迎所有业界同仁们贡献、讨论、改编。
|
||||
> - 本指南保持更新，欢迎任何人提出改进意见，如发现有错误或遗漏的点，请提 [Issue](https://github.com/yikeke/zh-style-guide/issues/new)。
|
||||
|
||||
希望本指南的出现能为日后业界标准的建立贡献一点力量。
|
||||
本指南规范了一种中文写作风格，主要用于技术文档的编写。素材来源于互联网，为各家中文文案风格指南的综合，旨在对中文技术文档的**语言风格、结构样式、内容元素、标点符号、格式排版**等方面给出参考规范。我希望本指南的出现能为日后业界标准的建立贡献一点力量。
|
||||
|
||||
## 目的
|
||||
|
||||
- 提高中文文案的可读性
|
||||
- 统一文档风格，保证公司对外输出形象一致
|
||||
- 避免不同的文档作者对同一问题反复作出决策，降低与文档相关的沟通成本
|
||||
- 提高中文文案的可读性。
|
||||
- 统一文档风格，保证组织对外输出形象一致。
|
||||
- 避免不同的文档作者对同一问题反复作出决策，降低与文档相关的沟通成本。
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 为编写中文文档的作者（如产品研发人员、tech writer 等）提供规范或建议
|
||||
- 审校文档过程中争议问题的裁决
|
||||
- 也可供软件界面、帮助文档等资料开发人员参考
|
||||
- 为编写中文文档的作者（如产品研发人员、技术写作人员等）提供规范或建议。
|
||||
- 审校文档过程中争议问题的裁决。
|
||||
- 也可供软件界面、帮助文档等资料开发人员参考。
|
||||
|
||||
## 使用原则
|
||||
|
||||
本指南是一本查询手册，建议初次阅读本指南时，先大致浏览目录章节结构，了解本指南涵盖的内容范围；之后就编写文档时碰到的实际问题，再回头查找相应规范。
|
||||
|
||||
## 用词说明
|
||||
## 标点符号和格式排版
|
||||
|
||||
本指南使用的表示“要求”的全部关键词已在下表第二列列出，具体释义请参见 [RFC2119](https://tools.ietf.org/html/rfc2119) 对相应词语做出的相关规定：
|
||||
- **合理使用标点符号**：标点符号是语言的重要组成部分，合理地使用标点符号能够帮助读者更好地理解文档。
|
||||
- **格式统一**：保持文档的格式统一，例如字体、字号、行间距等。
|
||||
|
||||
| RFC2119 中定义的关键词 | 对应的中文关键词 | 释义说明 |
|
||||
| -------------------------- | --------------------------- | ------------------------------------------------------------ |
|
||||
| MUST/REQUIRED/SHALL | 强制/必须/务必/只能 | 强制性规则，表示绝对要求这样做 |
|
||||
| MUST NOT/SHALL NOT | 禁止/不能/不要 | 强制性规则，表示绝对禁止这样做 |
|
||||
| SHOULD/RECOMMENDED | 应/应当/应该/建议/推荐 | 非强制性规则，表示一般情况下应该这样做，但在知悉全部后果的前提下，可以选择不这样做 |
|
||||
| SHOULD NOT/NOT RECOMMENDED | 不应当/不应该/不建议/不推荐 | 非强制性规则，表示一般情况下不应该这样做，但在知悉全部后果的前提下，可以选择这样做 |
|
||||
| MAY/OPTIONAL | 可以/可选 | 非强制性规则，表示这个要求是可选的，可以这样做，也可以不这样做 |
|
||||
## 修订和审查
|
||||
|
||||
> RFC (Request For Comments) 指关于互联网标准的正式文件，在这些文件的表述过程中，必须严格区分哪些是"建议" (suggestion)，哪些是"要求" (requirement)。所以，RFC2119 专门对五个关键词的涵义作出了规定，分别表示"要求"的严格程度。
|
||||
1. **定期修订**：定期修订文档，以保持其准确性和时效性。
|
||||
2. **多人审查**：邀请其他人审查文档，他们可能会发现你可能忽视的错误或者遗漏。
|
||||
|
||||
本指南主要针对中文技术文档的编写给出了一系列的规范和建议，包括语言风格、结构样式、内容元素、标点符号、格式排版等方面。我希望本指南能帮助你提高中文文档的编写质量，提高其可读性，同时也能减少与文档相关的沟通成本。
|
||||
|
||||
@ -1,135 +1,79 @@
|
||||
---
|
||||
id: 语言风格
|
||||
title: 语言风格
|
||||
sidebar_position: 2
|
||||
data: 2022年3月8日
|
||||
description: 语言风格
|
||||
keywords:
|
||||
- 文档
|
||||
- 语言
|
||||
- 风格
|
||||
tags:
|
||||
- 文档
|
||||
sidebar_position: 6
|
||||
author: 7Wate
|
||||
date: 2023-06-26
|
||||
---
|
||||
|
||||
## 对话式
|
||||
在技术文档的写作中，风格和语气的掌握是至关重要的。下面是一些关于技术文档写作的基本准则。
|
||||
|
||||
技术文档的语气应该平易近人、直截了当，推荐使用对话式，例如「你可以……」。技术文档的内容本身常常枯燥难懂，如果还采用过于正式的语言形式，就更是无聊乏味。
|
||||
## 对话式语气
|
||||
|
||||
文档中采用对话式的语气，并不意味就像日常说话那样。反而，口语常常冗长啰嗦、缺乏逻辑，在编写技术文档时应极力避免。
|
||||
技术文档的语言风格应该采用**平易近人、直截了当**的语气，比如使用「你可以…」这样的表达方式，避免过于正式或冗长的句子。
|
||||
|
||||
### 案例
|
||||
> 请使用下面的按钮来完成操作。❌
|
||||
>
|
||||
> 你可以使用下面的按钮来完成操作。
|
||||
|
||||
欢迎各位补充你身边的案例。
|
||||
## 客观礼貌的语气
|
||||
|
||||
## 客观礼貌
|
||||
技术文档的语气应客观并保持礼貌，不进行产品推销，**主要目的是传达技术信息**。应该使用友好而有礼貌的措辞，避免强硬或粗鲁的语气。在指导性文档中，尽量保持语气冷静、客观且简洁。
|
||||
|
||||
技术文档中应保持客观礼貌的语气，这样最容易拉近与读者的距离。具体要求有：
|
||||
> 你一定要按照这样做，否则会失败。❌
|
||||
>
|
||||
> 按照以下步骤操作，可以成功完成。
|
||||
|
||||
- 客观地传达技术信息，而不是在推销产品，否则易引起读者反感。
|
||||
- 保持一种友好礼貌的语气，不要显得强硬粗鲁。对于指导性文档，保持冷静、客观、简洁的语气。
|
||||
- 应避免使用拟人的写作手法，比如将人的特征、情感或动作赋予无生命的物体。
|
||||
- 文档中不要穿插太多玩笑，偶尔滑稽一次是可取的，这样能适当展现作者和公司的个性，使人印象深刻。但必须记住，技术文档的首要目的是向读者传达技术信息，不能为了追求轻松愉快的文档风格而使读者不明所以。
|
||||
- 不要使用使用反问句，不要让读者感受被质疑和挑战。
|
||||
- 不要轻易使用感叹句。感叹语气可能会让读者感受到被责备，建议仅用于特别强调的场景，例如：读者执行某项操作后，可能永久性地删除数据，需要提供强烈警示。
|
||||
- 不要轻易使用“请”、“抱歉”，除非真的对读者造成了困扰。
|
||||
- 避免过分亲切的称呼，例如“亲爱的”，建议始终使用“您”或“你”。
|
||||
## 简洁清晰地表达
|
||||
|
||||
### 案例
|
||||
简洁明了是技术文档的重要原则。**建议作者在完成初稿后，通读整篇文档**，删去没有明显作用的字、词、句，将文档长度缩短，但同时确保信息传递效果不受影响。避免使用冗长的句子和逻辑混乱的段落，尽量使用主动语态，明确阐述主语和宾语。
|
||||
|
||||
欢迎各位补充你身边的案例。
|
||||
> 如果在配置过程中出现问题，那么需要查看日志文件，然后分析日志文件中的错误信息，最后采取适当的措施来解决问题。❌
|
||||
>
|
||||
> 配置过程中出现问题时，查看日志文件，分析错误信息，并采取适当措施解决问题。
|
||||
|
||||
## 简洁清晰
|
||||
## 通俗易懂的语词
|
||||
|
||||
技术文档中应使用精练的语言。**建议作者在完成初稿后再通篇读一遍文档**，将文中所有对表达意思没有明显作用的字、词、句删去，在不影响表达效果的前提下把文案长度减到最短。具体要求有：
|
||||
**使用通俗易懂的词语是技术文档的基本要求。**避免使用行话、俚语或网络流行语，或故意使用谐音错别字。应使用标准的技术术语，避免过度使用缩略语或专业术语，尽量用简单明了的表达方式。
|
||||
|
||||
- 禁止啰嗦冗长
|
||||
- 禁止逻辑混乱
|
||||
- 同一文档中勿重复表达同一事物
|
||||
- 尽量用**主动时态**，尤其要**阐述清楚主语和宾语**
|
||||
> 这个软件有魔改功能，能让你的计算机跑得飞快！❌
|
||||
>
|
||||
> 这个软件有优化功能，可以提升计算机的运行速度。
|
||||
|
||||
### 案例
|
||||
## 以用户为导向
|
||||
|
||||
欢迎各位补充你身边的案例。
|
||||
**技术文档应以用户为导向，从用户的角度思考问题，提供有用的信息。**在撰写文档时，考虑文档的目标读者可能的技术水平和实际操作中可能遇到的问题，尽可能全面且清晰地解释技术信息，并提供更多的详细信息和解决方案。建议进行文档可用性测试，让无技术背景的测试人员参照文档进行操作，以确保文档的易用性。
|
||||
|
||||
## 通俗易懂
|
||||
> 在设置菜单中，选择适当的选项以进行配置。❌
|
||||
>
|
||||
> 在设置菜单中，选择相关选项，以便进行配置。
|
||||
|
||||
技术文档中不推荐使用只有特定人群才了解的语词。具体要求有：
|
||||
## 用词恰当和统一
|
||||
|
||||
- 不推荐使用行话黑话、俚语、脏话等，比如“魔改”（即做特殊的优化）、“CPU 打到 60%”（即 CPU 使用率为 60%）等行话黑话
|
||||
- 不推荐使用网络流行语，比如“墙裂”、“童鞋们”等流行语中故意的谐音错别字
|
||||
**在技术文档中，使用正确和一致的词汇非常重要。**你应避免使用可能引发冲突的词汇，并在同一篇或同一系列的技术文档中，保持一致的用词，避免造成混淆或阅读困难。
|
||||
|
||||
### 案例
|
||||
> 我们强烈推荐使用最新版本的软件。❌
|
||||
>
|
||||
> 建议使用最新版本的软件。
|
||||
|
||||
案例一：
|
||||
## 正确使用“的”、“地”、“得”
|
||||
|
||||
- 【错误】“欢迎各位 TW 们补充你身边的案例。”
|
||||
- 【正确】“欢迎各位文档工作者补充你身边的案例。”
|
||||
- 【解释】TW 是 Tech Writer 的意思，意为（技术）文档工程师。这是技术写作领域的从业者才知道的缩略语，为了让更广泛的受众理解，建议修改。
|
||||
> 调度系统会将数据迁移到其他的存储节点上。（形容词＋的＋名词）
|
||||
>
|
||||
> 数据库可以显式地使用事务。（副词＋地＋动词）
|
||||
>
|
||||
> 这个值不宜调得过大。（动词＋得＋副词）
|
||||
|
||||
欢迎各位补充你身边的案例。
|
||||
## 明确代词指代
|
||||
|
||||
## 用户导向
|
||||
你应确保代词的指代对象明确，避免造成读者的困惑。
|
||||
|
||||
技术文档中应该以用户为导向。为编写出可用性较高的文档，文档作者应尽量站在用户的角度思考问题。具体要求有：
|
||||
|
||||
- 文档作者应充分考虑文档**受众的技术水平分布**以及实际操作中可能出现的问题，尽可能全面、清晰地将技术信息普及给大众。
|
||||
- 对于操作型技术文档，除语言审校外，建议继续进行“文档可用性测试”——由一位无技术背景的测试人员参照该文档进行完整操作，如操作顺利成功，则该文档可用性测试通过；如失败，则需要继续修改完善文档。
|
||||
- 对于操作型技术文档，不仅要准确描述操作步骤，还应设身处地考虑用户可能面临的问题，提供进一步的详细信息。例如，对于需要输入的信息，提供输入格式等详细要求；对于报错信息，提供解决报错的可选操作；为方便用户排查错误，提供详细的错误码速查列表等等。
|
||||
|
||||
### 案例
|
||||
|
||||
欢迎各位补充你身边的案例。
|
||||
|
||||
## 用词恰当
|
||||
|
||||
用词恰当体现在两个方面：用词正确及用词统一。本节从禁用词和常用语两方面介绍了相应规范。
|
||||
|
||||
### 禁用词
|
||||
|
||||
用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考[新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》](https://www.digitaling.com/articles/22975.html)。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或公司节省不必要的麻烦。
|
||||
|
||||
以下是《新华社新闻报道中的禁用词（第一批）》中比较适用于技术文档的几点：
|
||||
|
||||
- 报道各种事实特别是产品、商品时不使用“最佳”、“最好”、“最著名”、“最新技术”、“最高水平”、“最先进水平”等具有强烈评价色彩的词语。
|
||||
- 对有身体伤疾的人士不使用“残废人”、“独眼龙”、“瞎子”、“聋子”、“傻子”、“呆子”、“弱智”等蔑称，而应使用“残疾人”、“盲人”、“聋人”、“智力障碍者”等词语。
|
||||
- 医药报道中不得含有“疗效最佳”、“根治”、“安全预防”、“安全无副作用”等词语，药品报道中不得含有“药到病除”、“无效退款”、“保险公司保险”、“最新技术”、“最高技术”、“最先进制法”、“药之王”、“国家级新药”等词语。
|
||||
- 如果产品文案中涉及多地域或可用区，需要正确使用涉及中国领土、主权和港澳台的词汇。比如：
|
||||
- 不得将台湾、香港、澳门与中国并列提及。比如不应使用“中港”、“中台”、“中澳”，可以使用“内地与香港”、“大陆与台湾”或“京港”、“沪港”、“闽台”等。
|
||||
- 不建议将中国某地区与其他国家并列提及。
|
||||
- 作为国家通讯社，新华社通稿中不应使用“哇噻”、“妈的”等俚语、脏话、黑话等。如果在引语中不能不使用这类词语，均应用括号加注，表明其内涵。近年来网络用语中对脏语进行缩略后新造的“SB”、“TMD”、“NB”等，也不得在报道中使用。
|
||||
|
||||
### 常用词
|
||||
|
||||
常用词是指在编写一篇或一系列技术文档时，经常被使用的词语，如人称代词、指示代词、语态助词、操作动词、技术术语等。
|
||||
|
||||
技术文档中必须正确使用各种常用词。具体要求有：
|
||||
|
||||
1. 必须用对“的”、“地”、“得”，不能乱用。
|
||||
- 【正确示例一】调度系统会将数据迁移到其他的存储节点上。（形容词＋的＋名词）
|
||||
- 【正确示例二】数据库可以显式地使用事务。（副词＋地＋动词）
|
||||
- 【正确示例三】这个值不宜调得过大。（动词＋得＋副词）
|
||||
2. 必须明确“其”、“该”、“此”、“这”等代词指代的内容，保证不造成歧义。
|
||||
- 【错误示例】如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将其 `image` 字段留空。
|
||||
- 【正确示例】如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将相应镜像的 `image` 字段留空。
|
||||
3. 不建议使用表示程度、强调语气的词，因为这类词词义通常比较模糊，或者显得主观绝对，建议用具体的数据或实例代替。例如，以下类型的词建议避免使用。
|
||||
- 表示程度的词：较多、较好、完全地、基本地、决定性的、最后的、仅仅、事实上、值得注意的
|
||||
- 【错误示例】很好地提升了性能。
|
||||
- 【分析】诸如“很好地”这样的词含义既模糊又主观，建议用具体的数据代替。另外，性能的含义也比较广泛，可以详细说明。
|
||||
- 【修改建议】性能提升了 50% 或者延迟从 10ms 降为 1ms。
|
||||
- 表示量的词：有些、非常、大量、一些、少许、部分、几乎、数倍等
|
||||
- 【错误示例】… 建表语句执行时间会是关闭该变量的数倍。
|
||||
- 【分析】对于用户来说，“数倍”的含义很模糊，三倍和八倍的差别是巨大的。这种情况下，可以说明一句影响建表语句执行时间的因素有哪些，并举一两个具体的实例加以说明。
|
||||
- 【修改建议】… 建表语句执行时间会是关闭该变量的数倍，具体多少倍取决于硬件和 PD 参数的配置。如当硬件为 … 且 PD 参数配置为 … 时，建表语句执行时间会是关闭该变量的 … 倍。
|
||||
4. 不建议使用冷僻、生造或者文言文的词语，应该使用现代汉语的常用表达方式。
|
||||
- 【错误示例】这是唯二的快速启动的方法。
|
||||
- 【正确示例】这是仅有的两种快速启动的方法。
|
||||
5. 禁止使用过多的形容词修饰名词。
|
||||
- 【错误示例】根据表名恢复被删除的表，会找到最近历史 DDL JOB 中的第一个是 DROP TABLE 类型的 DDL 且 DROP TABLE 的表名等于 RECOVER TABLE 语句中指定的表名的表进行恢复。
|
||||
- 【分析】这句话有太多修饰的词组，读起来很拗口，令人费解。这种情况下，建议适当断句以明晰语义。
|
||||
- 【正确示例】根据表名恢复被删除表的过程是：首先找到历史 DDL JOB 中最近一个 DROP TABLE 类型的 DDL 语句，并且该 DROP TABLE 语句中指定的表名等于 RECOVER TABLE 语句中指定的表名，再对这张表进行恢复。
|
||||
|
||||
另外，同一篇或同一系列技术文档中应尽可能统一用词，以降低阅读理解的难度。具体要求有：
|
||||
|
||||
1. 必须保证全文人称代词一致，人称不能反复改变。
|
||||
- 推荐使用“您”或“你”来指称文档读者或用户，两者皆可，禁止混用
|
||||
- 推荐使用“作者”、“文档作者”等第三人称形式来代指文档作者，不推荐使用“我”来代指文档作者，这样容易显得主观，也会在读者心中引起不必要的疑惑
|
||||
- 可以使用“我们”来代称整个公司，但建议少用
|
||||
2. 建议尽量使用主动语态，不使用被动语态。
|
||||
- 【错误示例】假如此软件尚未被安装，
|
||||
- 【正确示例】假如尚未安装这个软件，
|
||||
|
||||
【注意】汉语中使用**被字句**跟英语中使用**被动式**的含义是不同的。在英语中，使用被动式的目的是为了避免提及施事者，但在汉语中的被字句往往带有被动的负面含义。另外，在中文文档中使用主动语态能帮助**明确句子主语和宾语**，这对后续的技术翻译工作极为重要。
|
||||
> 如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将其 `image` 字段留空。❌
|
||||
>
|
||||
> 如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将相应镜像的 `image` 字段留空。
|
||||
|
||||
@ -1,10 +1,17 @@
|
||||
---
|
||||
id: 附录资料及相关说明
|
||||
title: 附录资料及相关说明
|
||||
sidebar_position: 9
|
||||
data: 2022年3月8日
|
||||
---
|
||||
title: 附录资料
|
||||
description: 中文文档指南附录资料
|
||||
keywords:
|
||||
|
||||
- 中文文档指南
|
||||
- 附录资料
|
||||
tags:
|
||||
- 文档
|
||||
sidebar_position: 7
|
||||
author: 7Wate
|
||||
date: 2023-06-26
|
||||
|
||||
---
|
||||
|
||||
针对编写的一系列技术文档，应提供相应的**术语表**和**缩略语表**作为附录资料，方便读者查阅。
|
||||
|
||||
@ -72,4 +79,4 @@ data: 2022年3月8日
|
||||
|
||||
语言文字：
|
||||
|
||||
《常见语言文字错误防范手册》. 周奇主编. 北京: 中国标准出版社, 2010.
|
||||
《常见语言文字错误防范手册》. 周奇主编. 北京: 中国标准出版社, 2010.
|
||||
Loading…
Reference in New Issue
Block a user