用词恰当

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

禁用词

用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考新华社 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. 建议尽量使用主动语态,不使用被动语态。

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

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

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