用词恰当

用词恰当体现在两个方面：用词正确及用词统一。本节从禁用词和常用语两方面介绍了相应规范。

禁用词

用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或公司节省不必要的麻烦。

以下是《新华社新闻报道中的禁用词（第一批）》中比较适用于技术文档的几点：

  • 报道各种事实特别是产品、商品时不使用“最佳”、“最好”、“最著名”、“最新技术”、“最高水平”、“最先进水平”等具有强烈评价色彩的词语。

  • 对有身体伤疾的人士不使用“残废人”、“独眼龙”、“瞎子”、“聋子”、“傻子”、“呆子”、“弱智”等蔑称，而应使用“残疾人”、“盲人”、“聋人”、“智力障碍者”等词语。

  • 医药报道中不得含有“疗效最佳”、“根治”、“安全预防”、“安全无副作用”等词语，药品报道中不得含有“药到病除”、“无效退款”、“保险公司保险”、“最新技术”、“最高技术”、“最先进制法”、“药之王”、“国家级新药”等词语。

  • 如果产品文案中涉及多地域或可用区，需要正确使用涉及中国领土、主权和港澳台的词汇。比如：

    • 不得将台湾、香港、澳门与中国并列提及。比如不应使用“中港”、“中台”、“中澳”，可以使用“内地与香港”、“大陆与台湾”或“京港”、“沪港”、“闽台”等。

    • 不建议将中国某地区与其他国家并列提及。

  • 作为国家通讯社，新华社通稿中不应使用“哇噻”、“妈的”等俚语、脏话、黑话等。如果在引语中不能不使用这类词语，均应用括号加注，表明其内涵。近年来网络用语中对脏语进行缩略后新造的“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. 建议尽量使用主动语态，不使用被动语态。

    • 【错误示例】假如此软件尚未被安装，

    • 【正确示例】假如尚未安装这个软件，

【注意】汉语中使用被字句跟英语中使用被动式的含义是不同的。在英语中，使用被动式的目的是为了避免提及施事者，但在汉语中的被字句往往带有被动的负面含义。另外，在中文文档中使用主动语态能帮助明确句子主语和宾语，这对后续的技术翻译工作极为重要。