语法

本节列举了中文技术文档中常见的几种语法错误,文档工程师及审校者应着重注意。

欢迎各位 TW 们补充你身边的案例。

成分残缺

【示例一】会话保持:在应用程序没有提供会话保持的功能下,HAProxy 可以提供该项功能。

【建议】会话保持:在应用程序没有提供会话保持功能的情况下,HAProxy 可以提供该项功能。

搭配不当

【示例一】HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写,并仍然负责该项目的维护,该在开源社区提供免费和版本迭代。

【存在的问题】“并仍然负责”的主语是 Willy Tarreau,不是 HAProxy。

【建议】HAProxy 是由 Linux 内核的核心贡献者 Willy Tarreau 于 2000 年编写,他现在仍然负责该项目的维护,并在开源社区免费提供版本迭代。

用词不当

倍数表达

技术文档中表达倍数建议遵循以下规范。

  • 数值的增加必须明确使用“增加了”或“增加到”,不能只使用“增加”。“了”表增量,“到”表定量。

    • 【错误示例】增加两倍

    • 【正确示例一】增加了两倍──即过去为一,现在为三。

    • 【正确示例二】增加到过去的两倍──即过去为一,现在为二。

  • 数值的减少必须明确使用“降低了”或“降低到”,不能只使用“降低”。“了”表增量,“到”表定量。

    • 【错误示例】降低 80%

    • 【正确示例一】降低了 80%──即原来是一百,现在是二十。

    • 【正确示例二】降低到 80%──即原来是一百,现在是八十。

  • 不能用“降低 N 倍”或“减少 N 倍”的表示法,要用“降低百分之几”或“减少百分之几”。

成分多余

【示例一】根据官方建议,目前稳定版本的 HAProxy 为稳定版 2.0 特性

【解释】官方目前建议使用 HAProxy 稳定版本 2.0,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 节点数超过部署节点的半数,即可正常提供服务。