diff --git a/docs/标准/技术文档/拼写与语法.md b/docs/标准/技术文档/拼写与语法.md new file mode 100644 index 00000000..18a292bc --- /dev/null +++ b/docs/标准/技术文档/拼写与语法.md @@ -0,0 +1,77 @@ +--- +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 节点数超过部署节点的半数,即可正常提供服务。 \ No newline at end of file