diff --git a/docs/标准/技术文档/语言风格.md b/docs/标准/技术文档/语言风格.md new file mode 100644 index 00000000..01fbf8c2 --- /dev/null +++ b/docs/标准/技术文档/语言风格.md @@ -0,0 +1,135 @@ +--- +id: 语言风格 +title: 语言风格 +sidebar_position: 2 +data: 2022年3月8日 +--- + +## 对话式 + +技术文档的语气应该平易近人、直截了当,推荐使用对话式,例如「你可以……」。技术文档的内容本身常常枯燥难懂,如果还采用过于正式的语言形式,就更是无聊乏味。 + +文档中采用对话式的语气,并不意味就像日常说话那样。反而,口语常常冗长啰嗦、缺乏逻辑,在编写技术文档时应极力避免。 + +### 案例 + +欢迎各位补充你身边的案例。 + +## 客观礼貌 + +技术文档中应保持客观礼貌的语气,这样最容易拉近与读者的距离。具体要求有: + +- 客观地传达技术信息,而不是在推销产品,否则易引起读者反感。 +- 保持一种友好礼貌的语气,不要显得强硬粗鲁。对于指导性文档,保持冷静、客观、简洁的语气。 +- 应避免使用拟人的写作手法,比如将人的特征、情感或动作赋予无生命的物体。 +- 文档中不要穿插太多玩笑,偶尔滑稽一次是可取的,这样能适当展现作者和公司的个性,使人印象深刻。但必须记住,技术文档的首要目的是向读者传达技术信息,不能为了追求轻松愉快的文档风格而使读者不明所以。 +- 不要使用使用反问句,不要让读者感受被质疑和挑战。 +- 不要轻易使用感叹句。感叹语气可能会让读者感受到被责备,建议仅用于特别强调的场景,例如:读者执行某项操作后,可能永久性地删除数据,需要提供强烈警示。 +- 不要轻易使用“请”、“抱歉”,除非真的对读者造成了困扰。 +- 避免过分亲切的称呼,例如“亲爱的”,建议始终使用“您”或“你”。 + +### 案例 + +欢迎各位补充你身边的案例。 + +## 简洁清晰 + +技术文档中应使用精练的语言。**建议作者在完成初稿后再通篇读一遍文档**,将文中所有对表达意思没有明显作用的字、词、句删去,在不影响表达效果的前提下把文案长度减到最短。具体要求有: + +- 禁止啰嗦冗长 +- 禁止逻辑混乱 +- 同一文档中勿重复表达同一事物 +- 尽量用**主动时态**,尤其要**阐述清楚主语和宾语** + +### 案例 + +欢迎各位补充你身边的案例。 + +## 通俗易懂 + +技术文档中不推荐使用只有特定人群才了解的语词。具体要求有: + +- 不推荐使用行话黑话、俚语、脏话等,比如“魔改”(即做特殊的优化)、“CPU 打到 60%”(即 CPU 使用率为 60%)等行话黑话 +- 不推荐使用网络流行语,比如“墙裂”、“童鞋们”等流行语中故意的谐音错别字 + +### 案例 + +案例一: + +- 【错误】“欢迎各位 TW 们补充你身边的案例。” +- 【正确】“欢迎各位文档工作者补充你身边的案例。” +- 【解释】TW 是 Tech Writer 的意思,意为(技术)文档工程师。这是技术写作领域的从业者才知道的缩略语,为了让更广泛的受众理解,建议修改。 + +欢迎各位补充你身边的案例。 + +## 用户导向 + +技术文档中应该以用户为导向。为编写出可用性较高的文档,文档作者应尽量站在用户的角度思考问题。具体要求有: + +- 文档作者应充分考虑文档**受众的技术水平分布**以及实际操作中可能出现的问题,尽可能全面、清晰地将技术信息普及给大众。 +- 对于操作型技术文档,除语言审校外,建议继续进行“文档可用性测试”——由一位无技术背景的测试人员参照该文档进行完整操作,如操作顺利成功,则该文档可用性测试通过;如失败,则需要继续修改完善文档。 +- 对于操作型技术文档,不仅要准确描述操作步骤,还应设身处地考虑用户可能面临的问题,提供进一步的详细信息。例如,对于需要输入的信息,提供输入格式等详细要求;对于报错信息,提供解决报错的可选操作;为方便用户排查错误,提供详细的错误码速查列表等等。 + +### 案例 + +欢迎各位补充你身边的案例。 + +## 用词恰当 + +用词恰当体现在两个方面:用词正确及用词统一。本节从禁用词和常用语两方面介绍了相应规范。 + +### 禁用词 + +用词正确体现在不使用有冒犯性的禁用词语。技术文档中的禁用词可参考[新华社 2015 年 11 月发布的《新华社新闻报道中的禁用词(第一批)》](https://www.digitaling.com/articles/22975.html)。技术文档虽不是新闻报道,但作为技术传播领域的大众传播物,应当同样考虑文档传播带来的影响。避免使用具有冒犯性的词语,能为个人或公司节省不必要的麻烦。 + +以下是《新华社新闻报道中的禁用词(第一批)》中比较适用于技术文档的几点: + +- 报道各种事实特别是产品、商品时不使用“最佳”、“最好”、“最著名”、“最新技术”、“最高水平”、“最先进水平”等具有强烈评价色彩的词语。 +- 对有身体伤疾的人士不使用“残废人”、“独眼龙”、“瞎子”、“聋子”、“傻子”、“呆子”、“弱智”等蔑称,而应使用“残疾人”、“盲人”、“聋人”、“智力障碍者”等词语。 +- 医药报道中不得含有“疗效最佳”、“根治”、“安全预防”、“安全无副作用”等词语,药品报道中不得含有“药到病除”、“无效退款”、“保险公司保险”、“最新技术”、“最高技术”、“最先进制法”、“药之王”、“国家级新药”等词语。 +- 如果产品文案中涉及多地域或可用区,需要正确使用涉及中国领土、主权和港澳台的词汇。比如: + - 不得将台湾、香港、澳门与中国并列提及。比如不应使用“中港”、“中台”、“中澳”,可以使用“内地与香港”、“大陆与台湾”或“京港”、“沪港”、“闽台”等。 + - 不建议将中国某地区与其他国家并列提及。 +- 作为国家通讯社,新华社通稿中不应使用“哇噻”、“妈的”等俚语、脏话、黑话等。如果在引语中不能不使用这类词语,均应用括号加注,表明其内涵。近年来网络用语中对脏语进行缩略后新造的“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. 建议尽量使用主动语态,不使用被动语态。 + - 【错误示例】假如此软件尚未被安装, + - 【正确示例】假如尚未安装这个软件, + +【注意】汉语中使用**被字句**跟英语中使用**被动式**的含义是不同的。在英语中,使用被动式的目的是为了避免提及施事者,但在汉语中的被字句往往带有被动的负面含义。另外,在中文文档中使用主动语态能帮助**明确句子主语和宾语**,这对后续的技术翻译工作极为重要。 \ No newline at end of file