标准：技术文档（语言风格）

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. 建议尽量使用主动语态，不使用被动语态。
+    - 【错误示例】假如此软件尚未被安装，
+    - 【正确示例】假如尚未安装这个软件，
+
+【注意】汉语中使用**被字句**跟英语中使用**被动式**的含义是不同的。在英语中，使用被动式的目的是为了避免提及施事者，但在汉语中的被字句往往带有被动的负面含义。另外，在中文文档中使用主动语态能帮助**明确句子主语和宾语**，这对后续的技术翻译工作极为重要。