11 KiB
| id | title | sidebar_position | data |
|---|---|---|---|
| 语言风格 | 语言风格 | 2 | 2022年3月8日 |
对话式
技术文档的语气应该平易近人、直截了当，推荐使用对话式，例如「你可以……」。技术文档的内容本身常常枯燥难懂，如果还采用过于正式的语言形式，就更是无聊乏味。
文档中采用对话式的语气，并不意味就像日常说话那样。反而，口语常常冗长啰嗦、缺乏逻辑，在编写技术文档时应极力避免。
案例
欢迎各位补充你身边的案例。
客观礼貌
技术文档中应保持客观礼貌的语气，这样最容易拉近与读者的距离。具体要求有：
- 客观地传达技术信息，而不是在推销产品，否则易引起读者反感。
- 保持一种友好礼貌的语气，不要显得强硬粗鲁。对于指导性文档，保持冷静、客观、简洁的语气。
- 应避免使用拟人的写作手法，比如将人的特征、情感或动作赋予无生命的物体。
- 文档中不要穿插太多玩笑，偶尔滑稽一次是可取的，这样能适当展现作者和公司的个性，使人印象深刻。但必须记住，技术文档的首要目的是向读者传达技术信息，不能为了追求轻松愉快的文档风格而使读者不明所以。
- 不要使用使用反问句，不要让读者感受被质疑和挑战。
- 不要轻易使用感叹句。感叹语气可能会让读者感受到被责备，建议仅用于特别强调的场景，例如：读者执行某项操作后，可能永久性地删除数据，需要提供强烈警示。
- 不要轻易使用“请”、“抱歉”，除非真的对读者造成了困扰。
- 避免过分亲切的称呼，例如“亲爱的”，建议始终使用“您”或“你”。
案例
欢迎各位补充你身边的案例。
简洁清晰
技术文档中应使用精练的语言。建议作者在完成初稿后再通篇读一遍文档，将文中所有对表达意思没有明显作用的字、词、句删去，在不影响表达效果的前提下把文案长度减到最短。具体要求有：
- 禁止啰嗦冗长
- 禁止逻辑混乱
- 同一文档中勿重复表达同一事物
- 尽量用主动时态，尤其要阐述清楚主语和宾语
案例
欢迎各位补充你身边的案例。
通俗易懂
技术文档中不推荐使用只有特定人群才了解的语词。具体要求有：
- 不推荐使用行话黑话、俚语、脏话等，比如“魔改”（即做特殊的优化）、“CPU 打到 60%”（即 CPU 使用率为 60%）等行话黑话
- 不推荐使用网络流行语，比如“墙裂”、“童鞋们”等流行语中故意的谐音错别字
案例
案例一：
- 【错误】“欢迎各位 TW 们补充你身边的案例。”
- 【正确】“欢迎各位文档工作者补充你身边的案例。”
- 【解释】TW 是 Tech Writer 的意思，意为（技术）文档工程师。这是技术写作领域的从业者才知道的缩略语，为了让更广泛的受众理解，建议修改。
欢迎各位补充你身边的案例。
用户导向
技术文档中应该以用户为导向。为编写出可用性较高的文档，文档作者应尽量站在用户的角度思考问题。具体要求有：
- 文档作者应充分考虑文档受众的技术水平分布以及实际操作中可能出现的问题，尽可能全面、清晰地将技术信息普及给大众。
- 对于操作型技术文档，除语言审校外，建议继续进行“文档可用性测试”——由一位无技术背景的测试人员参照该文档进行完整操作，如操作顺利成功，则该文档可用性测试通过；如失败，则需要继续修改完善文档。
- 对于操作型技术文档，不仅要准确描述操作步骤，还应设身处地考虑用户可能面临的问题，提供进一步的详细信息。例如，对于需要输入的信息，提供输入格式等详细要求；对于报错信息，提供解决报错的可选操作；为方便用户排查错误，提供详细的错误码速查列表等等。
案例
欢迎各位补充你身边的案例。
用词恰当
用词恰当体现在两个方面：用词正确及用词统一。本节从禁用词和常用语两方面介绍了相应规范。
禁用词
用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词（第一批）》。技术文档虽不是新闻报道，但作为技术传播领域的大众传播物，应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语，能为个人或公司节省不必要的麻烦。
以下是《新华社新闻报道中的禁用词（第一批）》中比较适用于技术文档的几点：
- 报道各种事实特别是产品、商品时不使用“最佳”、“最好”、“最著名”、“最新技术”、“最高水平”、“最先进水平”等具有强烈评价色彩的词语。
- 对有身体伤疾的人士不使用“残废人”、“独眼龙”、“瞎子”、“聋子”、“傻子”、“呆子”、“弱智”等蔑称，而应使用“残疾人”、“盲人”、“聋人”、“智力障碍者”等词语。
- 医药报道中不得含有“疗效最佳”、“根治”、“安全预防”、“安全无副作用”等词语，药品报道中不得含有“药到病除”、“无效退款”、“保险公司保险”、“最新技术”、“最高技术”、“最先进制法”、“药之王”、“国家级新药”等词语。
- 如果产品文案中涉及多地域或可用区，需要正确使用涉及中国领土、主权和港澳台的词汇。比如：
- 不得将台湾、香港、澳门与中国并列提及。比如不应使用“中港”、“中台”、“中澳”，可以使用“内地与香港”、“大陆与台湾”或“京港”、“沪港”、“闽台”等。
- 不建议将中国某地区与其他国家并列提及。
- 作为国家通讯社，新华社通稿中不应使用“哇噻”、“妈的”等俚语、脏话、黑话等。如果在引语中不能不使用这类词语，均应用括号加注，表明其内涵。近年来网络用语中对脏语进行缩略后新造的“SB”、“TMD”、“NB”等，也不得在报道中使用。
常用词
常用词是指在编写一篇或一系列技术文档时，经常被使用的词语，如人称代词、指示代词、语态助词、操作动词、技术术语等。
技术文档中必须正确使用各种常用词。具体要求有：
- 必须用对“的”、“地”、“得”，不能乱用。
- 【正确示例一】调度系统会将数据迁移到其他的存储节点上。（形容词＋的＋名词）
- 【正确示例二】数据库可以显式地使用事务。（副词＋地＋动词）
- 【正确示例三】这个值不宜调得过大。（动词＋得＋副词）
- 必须明确“其”、“该”、“此”、“这”等代词指代的内容，保证不造成歧义。
- 【错误示例】如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将其
image字段留空。 - 【正确示例】如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将相应镜像的
image字段留空。
- 【错误示例】如果希望从本地已编译好的二进制文件构建 PD、TiKV 或 TiDB 的镜像，需要将其
- 不建议使用表示程度、强调语气的词，因为这类词词义通常比较模糊，或者显得主观绝对，建议用具体的数据或实例代替。例如，以下类型的词建议避免使用。
- 表示程度的词：较多、较好、完全地、基本地、决定性的、最后的、仅仅、事实上、值得注意的
- 【错误示例】很好地提升了性能。
- 【分析】诸如“很好地”这样的词含义既模糊又主观，建议用具体的数据代替。另外，性能的含义也比较广泛，可以详细说明。
- 【修改建议】性能提升了 50% 或者延迟从 10ms 降为 1ms。
- 表示量的词：有些、非常、大量、一些、少许、部分、几乎、数倍等
- 【错误示例】… 建表语句执行时间会是关闭该变量的数倍。
- 【分析】对于用户来说，“数倍”的含义很模糊，三倍和八倍的差别是巨大的。这种情况下，可以说明一句影响建表语句执行时间的因素有哪些，并举一两个具体的实例加以说明。
- 【修改建议】… 建表语句执行时间会是关闭该变量的数倍，具体多少倍取决于硬件和 PD 参数的配置。如当硬件为 … 且 PD 参数配置为 … 时，建表语句执行时间会是关闭该变量的 … 倍。
- 表示程度的词：较多、较好、完全地、基本地、决定性的、最后的、仅仅、事实上、值得注意的
- 不建议使用冷僻、生造或者文言文的词语，应该使用现代汉语的常用表达方式。
- 【错误示例】这是唯二的快速启动的方法。
- 【正确示例】这是仅有的两种快速启动的方法。
- 禁止使用过多的形容词修饰名词。
- 【错误示例】根据表名恢复被删除的表，会找到最近历史 DDL JOB 中的第一个是 DROP TABLE 类型的 DDL 且 DROP TABLE 的表名等于 RECOVER TABLE 语句中指定的表名的表进行恢复。
- 【分析】这句话有太多修饰的词组，读起来很拗口，令人费解。这种情况下，建议适当断句以明晰语义。
- 【正确示例】根据表名恢复被删除表的过程是：首先找到历史 DDL JOB 中最近一个 DROP TABLE 类型的 DDL 语句，并且该 DROP TABLE 语句中指定的表名等于 RECOVER TABLE 语句中指定的表名，再对这张表进行恢复。
另外，同一篇或同一系列技术文档中应尽可能统一用词，以降低阅读理解的难度。具体要求有：
- 必须保证全文人称代词一致，人称不能反复改变。
- 推荐使用“您”或“你”来指称文档读者或用户，两者皆可，禁止混用
- 推荐使用“作者”、“文档作者”等第三人称形式来代指文档作者，不推荐使用“我”来代指文档作者，这样容易显得主观，也会在读者心中引起不必要的疑惑
- 可以使用“我们”来代称整个公司，但建议少用
- 建议尽量使用主动语态，不使用被动语态。
- 【错误示例】假如此软件尚未被安装，
- 【正确示例】假如尚未安装这个软件，
【注意】汉语中使用被字句跟英语中使用被动式的含义是不同的。在英语中，使用被动式的目的是为了避免提及施事者，但在汉语中的被字句往往带有被动的负面含义。另外，在中文文档中使用主动语态能帮助明确句子主语和宾语，这对后续的技术翻译工作极为重要。