标准：技术文档（文档内容）
This commit is contained in:
parent
c95bf6d83d
commit
ab4b127963
431
docs/标准/技术文档/文档内容.md
Normal file
431
docs/标准/技术文档/文档内容.md
Normal file
@ -0,0 +1,431 @@
|
||||
---
|
||||
id: 文档内容
|
||||
title: 文档内容
|
||||
sidebar_position: 4
|
||||
data: 2022年3月8日
|
||||
---
|
||||
|
||||
## 空白符号
|
||||
|
||||
空白符号包括空格、空行等，其中空格分为半角空格和全角空格。
|
||||
|
||||
### 空白的使用
|
||||
|
||||
技术文档中使用空白符号建议遵循以下规范。
|
||||
|
||||
| 空白类型 | 相应规范 |
|
||||
| -------- | ------------------------------------------------------------ |
|
||||
| 空格 | - 禁止使用全角空格，**一律使用半角空格**。 - 中文字符（包括汉字和中文标点符号）和中文字符之间禁止空半角空格。 - **英文字符和阿拉伯数字**一般使用半角格式，所以应使用半角空格包围，以下情况例外：1）位于句首时，左边空格省略； 2）其右侧为半角标点或全角标点时，右边空格省略。 - 除表示缩进、列表级别、代码块中固有空格、Markdown 表格中的空格外，禁止连续出现两个及以上的半角空格。 - 不建议使用 Tab（制表符）替换空格。 |
|
||||
| 空行 | - 不同段落间建议使用一个空行隔开。 - 不同排版格式之间建议使用一个空行隔开，如标题与紧跟着的正文之间，正文与代码块之间、正文与表格之间等。 - 禁止连续出现两个及以上的空行。 |
|
||||
| 其他 | 行宽：相同排版格式内保持一致即可，可自由在 80、120 字符中选择，原则上不超过 160 字符宽。 |
|
||||
|
||||
### Tab 和空格的使用
|
||||
|
||||
技术文档中经常使用 Tab 键和空格键进行缩进和对齐。由于在不同的编辑器里 Tab 的默认长度可能不一致，用 Tab 键设置缩进可能导致格式混乱。如果使用空格键设置缩进，则用任何编辑器打开文档都会显示一样的对齐效果。
|
||||
|
||||
因此建议：
|
||||
|
||||
- 使用空格键而不用 Tab 键进行缩进或对齐。
|
||||
- 使用 Tab 键缩进是可以接受的，但**禁止混用 Tab 和空格**进行缩进。
|
||||
- 在 Visual Studio Code 等编辑器里统一设置一个 Tab 等于四个半角空格。
|
||||
|
||||
## 列表
|
||||
|
||||
当有 3 项或更多重要信息需要展示时，纵向列表是最清晰且吸引眼球的方式。但如果项目少于 3 项且无需特别强调，将其直接放在句子中通常效果更好。
|
||||
|
||||
也可以创建多级嵌套列表，在某一级别下另起一行，缩进**四个空格**即可开始更低级别的列表。
|
||||
|
||||
### 无序列表和有序列表
|
||||
|
||||
技术文档中的列表分为有序列表 (ordered list) 和无序列表 (unordered list) 两种。一般而言，**当列表项之间的顺序不重要时，使用无序列表；当各项之间的顺序很重要时，使用有序列表。**
|
||||
|
||||
【无序列表示例】
|
||||
|
||||
目前，TiDB 数据库使用了以下组件：
|
||||
|
||||
- Prometheus Server：用于收集和存储时间序列数据。
|
||||
- Client 代码库：用于定制程序中需要的 Metric。
|
||||
- Alertmanager：用于实现报警机制。
|
||||
|
||||
【有序列表示例】
|
||||
|
||||
解决办法：
|
||||
|
||||
1. 编辑数据源文件。
|
||||
2. 手动创建所有的表。
|
||||
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 个步骤。 | 无 | 无 |
|
||||
|
||||
## 表格
|
||||
|
||||
技术文档中使用表格建议遵循以下规范。
|
||||
|
||||
1. 样式规范
|
||||
|
||||
- 单元格中的所有内容都**建议保持左对齐**。
|
||||
- 所有表格都需要有表头描述，即表格第一行中描述各列内容的短语。
|
||||
- 保证表格同一行的单元格不跨页。
|
||||
- 每个表格下都要空一行，这一空行的样式为正文。如遇到换页的情况，表格后的空行在新页的第一行，则这行空行必须删除。
|
||||
|
||||
2. 表头规范
|
||||
|
||||
同一技术文档或产品手册中相同类型表格的表头描述需要保持一致。
|
||||
|
||||
【注意】对参数进行说明的表，应该统一表头描述，不要出现“参数说明”、“参数解释”、“参数含义”、“参数意义”等不同的描述。
|
||||
|
||||
3. 单元格内容规范
|
||||
|
||||
- 表格中的内容应该尽量简练，文字表述风格保持一致。避免长篇大段的说明，建议单元格中的内容所占行数不要超过 6 行。
|
||||
- 不出现空白的单元格。建议无内容单元格填写“无”或特定含义符号（如“/”）。若使用特定含义符号，需说明符号代表的意义。
|
||||
- 单元格内容避免重复。如果多个单元格中的内容相同，建议将内容复制或者采用多个单元格合并的方式，不要使用“同上”。
|
||||
|
||||
4. 表说明规范
|
||||
|
||||
表说明即表格之前或之后的一行表描述，可能带有序号或编号，主要是为了简要描述表格内容。
|
||||
|
||||
- 表说明采用名词词组形式。
|
||||
- 表说明简明扼要，长度不能超过表的宽度。
|
||||
- 同类表格的表说明在全文中风格保持统一。
|
||||
|
||||
## 图形和图片
|
||||
|
||||
技术文档中插入图形与图片建议遵循以下规范。
|
||||
|
||||
- 必须使用清晰可辨的图形图片。
|
||||
- 中文文档里图形图片上的文字建议都用中文，如果原图文字是其他语言，应该先做好图片本地化工作。
|
||||
- 文字建议使用**免费开源可商用字体**，以免引入法律风险。如不确定使用的字体是否能商用，可以在 [360 查字体](http://fonts.safe.360.cn/)网站中查证。
|
||||
- 同一文档内图形图片上的中文应该统一字体（如“思源黑体”），英文和数字也要统一字体（如“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)。
|
||||
|
||||
## 注意和说明
|
||||
|
||||
注意和说明内容在技术文档中起强调作用。技术文档中使用注意和说明建议遵循以下规范。
|
||||
|
||||
- 根据提示内容的级别和分类使用不同的文字描述。例如，分类可以包括“危险”、“警告”、“小心”、“注意”、“说明”、“建议”、“举例”、“错误”等。
|
||||
- 注意和说明中不能包含表格和图形。
|
||||
- 注意和说明的内容不能过长，建议不要超过 4 行。
|
||||
|
||||
## 代码块和代码注释
|
||||
|
||||
技术文档中插入代码块建议遵循以下规范。
|
||||
|
||||
- 代码块前后必须加上一行空行。
|
||||
- 代码块要注意缩进。例如，当前代码块属于列表项下的内容，则要在该列表项的缩进基础上再缩进四格。
|
||||
- 如果前端支持，建议高亮代码块，方便阅读。
|
||||
- 如果前端支持，建议为代码块加上可供用户直接复制代码的按钮，提高文档易用性。
|
||||
|
||||
代码注释一般出现在多行代码块中。技术文档中插入代码注释建议遵循以下规范。
|
||||
|
||||
- 一行注释不能太长，太长时应适当进行断句并切分到下一行。
|
||||
- 一行注释末尾建议加上标点符号，一般是句号；与下一行的内容承接时，用逗号。
|
||||
- 必须根据代码块中定义的语法选择相应的注释符，不能自创注释符。
|
||||
|
||||
## 链接
|
||||
|
||||
技术文档中的链接将用户引导至同一文档中的其他标题、其他相邻文档或外部站点。本节主要介绍在使用 Markdown 语言编写的技术文档中使用链接建议遵循的规范。
|
||||
|
||||
Markdown 中的链接格式示例：
|
||||
|
||||
- 链至同一文档中的其他标题：`[产品架构](#产品架构)`
|
||||
- 链至其他相邻文档：`[产品架构](../docs/architecture.md)`
|
||||
- 链至外部站点：`[贡献者指南](https://docs.microsoft.com/zh-cn/contribute/)`
|
||||
|
||||
### 链接的描述
|
||||
|
||||
Markdown 链接中方括号 `[]` 里的内容为该链接的描述性文本。链接的描述需要符合以下规范。
|
||||
|
||||
- 链接描述必须能概括所链文档或页面的大致内容，这有利于搜索引擎优化。例如，链接描述可以是所链页面的标题。
|
||||
- 【错误示例】
|
||||
- 详情参见 `[trouble-shooting.md](trouble-shooting.md)`
|
||||
- 详情请点击`[这里](trouble-shooting.md)`
|
||||
- 【正确示例】
|
||||
- 关于以上配置项的更多细节，参见`[功能配置集](#功能配置集)`的相关配置项。
|
||||
- 详情参见`[故障诊断文档](trouble-shooting.md)`。
|
||||
- 同类型的链接描述应尽量统一风格。例如：同一文档内不宜多次出现“详情参见”、“详情参阅”、“具体见”、“具体请见”等表达相同意思的不同描述。
|
||||
|
||||
### 链接的路径
|
||||
|
||||
Markdown 链接中圆括号 `()` 里的内容即为该链接的路径。链接的路径需要符合以下规范。
|
||||
|
||||
- **如链至其他相邻文档，且链接的文档篇幅较长，建议链接至锚点**。链接至锚点即链接至某级标题处。Markdown 支持在链接路径的文件名后加“#标题名称”，即可以链接至该文件的特定标题处。
|
||||
|
||||
- 【示例】`[配置文件](trouble-shooting.md#配置文件)`这个链接将链至 trouble-shooting.md 文件的“配置文件”标题下。
|
||||
|
||||
- 链接路径应尽量统一风格。例如，链接至非外部站点时应统一使用相对路径或绝对路径，不建议混用相对路径和绝对路径。
|
||||
|
||||
- 建议减少将用户链至外部站点的次数，以免外部站点的页面失效而影响用户体验。
|
||||
|
||||
> 外部站点的含义：A 网站的文档中出现了一个 B 链接，如果 B 与 A 的域名或服务器不一样，则对于 A 网站的文档来说，B 链接为外部站点。例如：cloud.google.com 相对于 support.google.com 为内部站点；cloud.google.com 相对于 kubernetes.io 为外部站点。
|
||||
|
||||
- **如果必须将用户链至外部站点，建议在该外链后加上明显的标示，提醒用户该链接将前往外部站点。**
|
||||
|
||||
> 由于不同网站的使用条款和隐私政策不同，用户使用当前站点，一般默认用户已经接受了当前站点的法律条文。跳出当前站点之前，网站维护者有责任提醒用户当前的链接是去往外部站点，跳出去之后如果用户发生问题，不是当前站点的责任。
|
||||
|
||||
- 【示例一】如果前端能力足够，可以在外链后加上通用的外链 icon 效果，比如：[贡献者名单](https://github.com/yikeke/zh-style-guide/graphs/contributors)。
|
||||
- 【示例二】在 Markdown 中，可以简单在链接的路径后加上 `"点击前往外部站点"` 或者 `"点击前往 XXX 网站"`等信息，如 `[链接的描述](链接的路径 "前往外部链接的提示")`，即可在正常渲染下，实现鼠标悬停在超链接上时出现提示的效果。
|
||||
|
||||
## 引用
|
||||
|
||||
技术文档中使用引用建议遵循以下规范。
|
||||
|
||||
- 当某内容在其他地方已经详细描述过、不适合在正文中再次介绍时，可以使用引用。
|
||||
- 对于必须引用但内容很少（少于 100 字）的情况，建议直接在该处重新描述一遍。
|
||||
- 必须保证引用的位置准确。
|
||||
|
||||
技术文档中引用第三方内容建议遵循以下规范。
|
||||
|
||||
- 引用他人的语句时，应注明出处。
|
||||
- 【示例】One man’s constant is another man’s variable. — Alan Perlis
|
||||
- 全篇转载时，应在全文开头显著位置注明作者和出处，并链接至原文。
|
||||
- 【示例】本文转载自 WikiQuote
|
||||
- 使用外部图片时，必须在图片下方或文末标明来源。
|
||||
- 【示例】本文部分图片来自 Wikipedia
|
||||
|
||||
## 缩略语
|
||||
|
||||
中文技术文档中的缩略语有两种：汉语缩略语和英语缩略语。下文分别介绍了两者的概念、特点及使用规范。
|
||||
|
||||
### 汉语缩略语
|
||||
|
||||
汉语缩略语是由较长的中文语词缩短省略而成的语词，如“人大”、“重启”、“停机”、“绑核”等。
|
||||
|
||||
由于汉语缩略语一般数量较少、含义明确，在技术文档中只要保证该缩略语通俗易懂、不造成歧义，原则上不限制使用次数。如果某词在文档中必须大量使用，但其缩略语不常见，建议在该词第一次出现时说明情况，提示读者下文中将以缩略语的形式称呼该词。
|
||||
|
||||
### 英语缩略语
|
||||
|
||||
英语缩略语数量巨大、种类繁多，出现在中文技术文档中的主要有三种：首字母缩略词 (acronym)、字母词 (initialism) 和缩写词 (shortened word) 。三者的区别是：
|
||||
|
||||
- 首字母缩略词：由每个词的首字母组成，以词的形式发音。
|
||||
- 【示例】NATO 代表 North Atlantic Treaty Organization
|
||||
- 字母词：也是由每个词的首字母组成，但按字母逐字发音。
|
||||
- 【示例】FBI 代表 Federal Bureau of Investigation
|
||||
- 缩写词：由较长的中文语词缩短省略而成的语词。
|
||||
- 【示例】App 代表 Application；demo 代表 demonstration
|
||||
|
||||
在技术文档中使用英语缩略语建议遵循以下规范。
|
||||
|
||||
- 不建议在标题中解释英文缩略语，以免造成标题冗长。
|
||||
- 建议在正文中第一次出现缩略语的地方解释其完整含义。
|
||||
- 某词用缩略语进行代称时，必须在该词第一次出现时说明情况，提示读者下文中将以缩略语的形式称呼该词。
|
||||
- 禁止使用不规范的缩略语，例如，用“16c32g”表示“16 核、32 GB”；用“10w”表示 10 万。
|
||||
|
||||
## 数字
|
||||
|
||||
在中文语境中，数字有两种形式：第一种是汉字数字，如“二”、“十”等；第二种是阿拉伯数字，如“2”、“10”等。
|
||||
|
||||
技术文档中汉字数字和阿拉伯数字的用法建议遵循以下规范。
|
||||
|
||||
### 数字形式的选用
|
||||
|
||||
除一些惯用场景和特殊场景外，如果希望达到**突出强调、易于辨识**的效果，应采用阿拉伯数字；如果希望突出**正式、庄重**的表达效果，应使用汉字数字。
|
||||
|
||||
#### 选用阿拉伯数字
|
||||
|
||||
| 适用场景 | 示例 |
|
||||
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| 用于计量（即用于加、减、乘、除等数学运算）的数字，如正负整数、小数、百分比、比例、分数等。 | -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 点整 |
|
||||
|
||||
#### 选用汉字数字
|
||||
|
||||
| 适用场景 | 示例 |
|
||||
| ------------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| 数字连用表示的概数、含“几”的概数等 | 三四个月、一二十个、十五六岁、五六万套、五六十年前、几千、二十几、一百几十、几十万分之一 |
|
||||
| 干支纪年、农历月日、历史朝代纪年及其他传统上采用汉字形式的非公历纪年 | 腊月二十三、正月初五、八月十五中秋、秦文公四十四年、太平天国庚申十年九月二十三号、日本庆应三年、丙寅年十月十五日 |
|
||||
| 汉语中长期使用且已稳定下来的包含汉字数字形式的词语 | 星期五、四氧化三铁、一方面、不二法门、二八年华、二百五、八国联军、五四运动、万一、一旦、四书五经、七上八下、不管三七二十一、半斤八两、“一·二八”事变、“一·二九”运动 |
|
||||
| 希望突出庄重典雅的表达效果时 | 六方会谈（不写为“6 方会谈”）、十一届全国人大一次会议（不写为“11 届全国人大 1 次会议”） |
|
||||
|
||||
#### 选用阿拉伯数字和汉字数字均可
|
||||
|
||||
如果表达计量或编号所需要用到的数字个数不多，选择阿拉伯数字还是汉字数字在书写的简洁性及辨识的清晰性两方面没有明显差异时，两种形式均可使用。
|
||||
|
||||
如下表所示，在不同场景下，下列两种形式均可使用：
|
||||
|
||||
| 阿拉伯数字形式 | 汉字数字形式 |
|
||||
| ----------------- | -------------------- |
|
||||
| 3 倍 | 三倍 |
|
||||
| 100 多个数据中心 | 一百多个数据中心 |
|
||||
| 20 余次 | 二十余次 |
|
||||
| 约 300 人 | 约三百人 |
|
||||
| 40 左右 | 四十左右 |
|
||||
| 第 40 页 | 第四十页 |
|
||||
| 第 9 天 | 第九天 |
|
||||
| 第 4 季度 | 第四季度 |
|
||||
| 共 128 位贡献者 | 共一百二十八位贡献者 |
|
||||
| 0.5 | 零点五 |
|
||||
| 1/3 | 三分之一 |
|
||||
| 公元前 8 世纪 | 公元前八世纪 |
|
||||
| 20 世纪 80 年代 | 二十世纪八十年代 |
|
||||
| 公元 278 年 | 公元二七八年 |
|
||||
| 1997 年 4 月 1 日 | 一九九七年四月一日 |
|
||||
| 下午 4 点 27 分 | 下午四点二十七分 |
|
||||
|
||||
#### 其他注意事项
|
||||
|
||||
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 班”）
|
||||
|
||||
3. 有法律效力的文件、公告文件或财务文件中可同时采用汉字数字和阿拉伯数字。
|
||||
|
||||
- 【示例一】2019 年 7 月保险账户结算日利率为万分之一点五七五零 (0.015750%)
|
||||
- 【示例二】35.5 元（35 元 5 角、三十五元五角或者叁拾伍元伍角）
|
||||
|
||||
### 阿拉伯数字的使用
|
||||
|
||||
技术文档中使用阿拉伯数字建议遵循如下规范。
|
||||
|
||||
#### 格式
|
||||
|
||||
书写格式上建议遵循如下字体、空格、换行规范。
|
||||
|
||||
- 数字与英文字母一样，一律使用**半角形式**（即半个汉字位置），不得使用全角形式。
|
||||
- 【错误示例】每２分钟导入一个２５６ MB 的数据文件。
|
||||
- 【正确示例】每 2 分钟导入一个 256 MB 的数据文件。
|
||||
- 在不作任何后期排版处理的前提下，建议半角数字两旁各空一个空格。
|
||||
- 【错误示例】每2分钟导入一个256MB 的数据文件。
|
||||
- 【正确示例】每 2 分钟导入一个 256 MB 的数据文件。
|
||||
- 一个用阿拉伯数字书写的数值必须在同一行中，**不能断开移行**。
|
||||
|
||||
#### 多位数值
|
||||
|
||||
技术文档中书写多位数值建议遵循如下规范。
|
||||
|
||||
- 数值巨大的精确数字，建议使用“亿、万”作单位。如，10 亿 231 万 3245 人。
|
||||
- 数值为千位以上，建议添加半角逗号“,”作为分节符。
|
||||
- 多位整数从右到左分节，每三位一节，如 2,345,567,456。
|
||||
- 小数部分不分节，如 19,256,289.23456。
|
||||
- 四位以内的整数可以不分节，如 1289。
|
||||
|
||||
#### 数值范围
|
||||
|
||||
技术文档中书写数值范围建议遵循如下规范。
|
||||
|
||||
- 在表示数值的范围时，可采用浪纹式连接号“～”或一字线连接号“—”。
|
||||
|
||||
【示例】-36～-8 ℃、400—429 页、100—198 kg、12500～20000 元
|
||||
|
||||
- 前后两个数值的附加符号或计量单位相同时，在**不造成歧义**的情况下，前一个数值的附加符号或计量单位可省略。
|
||||
|
||||
【示例】9 亿～20 亿（可写为 9～20 亿）、13 万元～100 万元（可写为 13～100 万元）、64 MB～1024 MB（可写为 64～1024 MB）、15%～30%（可写为 15～30%）
|
||||
|
||||
#### 年月日
|
||||
|
||||
技术文档中使用阿拉伯数字表示年月日，建议遵循如下规范。
|
||||
|
||||
- 四位数字表示的年份不应简写为两位数字。如“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。
|
||||
|
||||
#### 时分秒
|
||||
|
||||
技术文档中使用阿拉伯数字表示时分秒，建议遵循如下规范。
|
||||
|
||||
- 计时方式既可采用 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)）。
|
||||
Loading…
Reference in New Issue
Block a user