HOW - 技术文档写作技巧（Google Tech Writing）

一、背景

1.1 Google Tech Writing

Google 推出了一系列旨在提高软件工程师和相关职业人员技术写作技能的课程：Technical Writing

Every engineer is also a writer. This collection of courses and learning resources aims to improve your technical documentation. Learn how to plan and author technical documents. You can also learn about the role of technical writers at Google.

这些课程设计既包括基础内容，也涵盖中级写作技巧，重点在于如何写出清晰、简洁且针对目标受众的文档。

针对以下人群：

• 软件工程师和计算机科学学生。
• 产品经理等与工程相关的职业。
• 任何从事或维护技术文档的人。

学习目标：

• 编写清晰、简洁和结构良好的技术文档。
• 使用主动语态，避免被动句式。
• 有效地使用列表和段落组织信息。
• 编辑和修订文档以提高可读性和理解度。
• 理解和应用文档可访问性原则。

这些课程是免费的，可以在线访问。组织也可以使用Google提供的材料内部举办现场课程。更多详细信息和课程访问可访问 Google开发者技术写作课程页面。

1.2 课程概述

1. 技术写作一（Technical Writing One）

该课程介绍技术写作的基础知识，强调在开始写作之前了解受众的重要性，使用清晰简洁的语言，以及如何有效地组织文档。

主要内容包括：

• 一致使用术语和缩写。
• 识别和消除模糊的代词。
• 使用主动语态代替被动语态。
• 创建有效的列表和段落。
• 确定受众需求和文档范围。

2. 技术写作二（Technical Writing Two）

在基础课程的基础上进一步深入，涵盖更复杂的写作主题。

内容包括：

• 高级编辑技术。
• 为可访问性而写作。
• 创建有用的错误消息。

3. 为可访问性而写的技术写作（Tech Writing for Accessibility）

此课程侧重于使文档对所有用户（包括残障用户）都易于访问。课程内容涵盖编写包容性和可访问性技术内容的最佳实践。

二、第一部分：基础知识

2.1 单词

参考资料：

• 中文文案排版指北
• Word list

1. 新词及术语

1.1 识别目标受众可能不熟悉的新词，要么提供一个单词释义的超链接，要么直接提供一个准确的解释，以帮助读者理解。假如有太多新词的话，整理一个术语表。

示例：

• 文档内容：在使用 API（应用程序编程接口） 时，我们需要注意它的请求方法。
• 提供解释或超链接：在使用 API（应用程序编程接口）时，我们需要注意它的请求方法。
• 术语表示例：

  | 术语       | 解释                         |
  | ---------- | ---------------------------- |
  | API        | 应用程序编程接口              |
  | JSON       | 一种轻量级的数据交换格式      |
  | REST       | 表现层状态转移，API的一种架构 |
  

1.2 对同一概念的用词全篇要保持一致。说明文档中途切换名称的叫法，读者的大脑也难以准确感知。

示例：

• 不一致的用词：我们需要调用 API 接口获取数据。这个 应用程序编程接口 提供了多种功能。
• 保持一致的用词：我们需要调用 API 获取数据。这个 API 提供了多种功能。

1.3 使用人们不熟悉的缩写词时，在缩写词首次出现时添加全称，后续就可以使用缩写词。不要发明一些可能没什么人用，后续也不会被频繁使用的缩写。

示例：

• 首次出现时添加全称：在处理数据时，我们使用了 JSON（JavaScript Object Notation） 格式。使用 JSON 格式能提高数据传输的效率。

1.4 尽可能消除代词歧义（例如他、它、这、那）。不合适的代词就是留给读者的空指针。大部分情况下，使用原来的名词会比使用代词更精确。特别对于原词和代词之间假如插入了其他的词语，就不应该使用代词。

示例：

• 代词歧义：在应用中，模块会定期更新。它的主要功能是处理数据。
• 消除歧义：在应用中，模块会定期更新。模块的主要功能是处理数据。

2. 单词书写

1. 空格。中英文之间需要增加空格；中文与数字之间需要增加空格；数字与单位之间需要增加空格（度或百分比除外，如 15% 或 33.3°）；全角标点与其他字符之间不加空格（如 iPhone，）。

2. 标点符号。不重复使用标点符号；区分全角与半角；数字使用半角字符（如 100 和 １００）；遇到完整的英文整句、特殊名词，其内容应该使用半角标点（如 推荐你阅读《Hackers & Painters: Big Ideas from the Computer Age》和 推荐你阅读《Hackers＆Painters：Big Ideas from the Computer Age》，冒号应该使用半角）。

3. 名词

1. 专有名词使用正确的大小写。如 GitHub 和 GITHUB。
2. 不要使用不地道的缩写。如 AngularJS 和 angular。

2.2 句子

1. 语态选择

1.1 尽可能使用主动语态，主动语态比被动语态更清楚。大多数读者的大脑也会先将被动语态转化为主动语态，再进行理解。

示例：

• 被动语态：测试用例被开发人员创建和执行。
• 主动语态：开发人员创建和执行测试用例。

使用主动语态时，句子的主语（开发人员）直接说明谁在进行动作（创建和执行），使句子更加直接和清晰。

1.2 有时被动语态会省略主语，这样会增大理解难度。

示例：

• 被动语态（省略主语）：代码需要在提交前测试。
• 主动语态：开发人员需要在提交前测试代码。

被动语态中省略了主语“开发人员”，读者需要猜测是谁在执行测试的动作。而在主动语态中，明确指出了“开发人员”需要测试代码，句子更加清晰明确。

2. 语义表达

2.1 使用精确、具体的动词

示例：

• 模糊动词：进行测试。
• 精确动词：执行测试。
• 模糊动词：获取信息。
• 精确动词：检索信息。

解释：使用“执行”代替“进行”，使用“检索”代替“获取”，使得动词更具体，动作更明确。

2.2 减少使用语义宽松的特定形容词

示例：

• 宽松的形容词：这是一款优秀的软件。
• 减少宽松的形容词：这是一款功能齐全的软件。
• 宽松的形容词：这个算法很快。
• 减少宽松的形容词：这个算法在O(n)时间复杂度内完成。

解释：使用“功能齐全的”代替“优秀的”，使用具体的“在O(n)时间复杂度内完成”代替“很快”，让描述更具体、更准确。

2.3 让技术读者感知事实数据，而不是营销措辞

示例：

• 营销措辞：我们的产品是市场上最好的解决方案。
• 事实数据：我们的产品在最近的行业评估中获得了90%的满意度评分。
• 营销措辞：这个工具可以极大地提高效率。
• 事实数据：这个工具可以将处理时间减少40%。

解释：使用具体的评估数据和实际性能提升数据，代替含糊的营销用语，使得读者能更好地理解产品的实际效果。

3. 语句精炼

3.1 拆分长句，让每个句子只聚焦于一个观点、想法或者概念

示例：

• 错误：1950 年代后期是编程语言的关键时代，因为 IBM 在 1957 年推出了 Fortran，而 John McCarthy 在次年推出了 Lisp，这为程序员提供了解决问题的迭代方式和递归方式。
• 正确：1950 年代后期是编程语言的关键时代。IBM 于 1957 年推出了 Fortran。第二年，John McCarthy 发明了 Lisp。到 1950 年代后期，程序员可以迭代或递归地解决问题。

3.2 拆分带着连词或并列语义的长句，用列表来说明

示例：

• 错误：要改变循环的正常流程，您可以使用 break 语句（跳出当前循环）或 continue 语句（跳过当前循环的当前迭代的剩余部分）。
• 正确：要改变循环的正常流程，请调用以下语句之一：
  • break，跳出当前循环。
  • continue，跳过当前循环的当前迭代的剩余部分。

3.3 精简无用词语

示例：

• 错误：将句子从被动语态改为主动语态可以增强对关键点的澄清。
• 正确：将句子从被动语态改为主动语态可以阐明要点。

3.4 减少使用从句

假如从句不是延伸主句的语义，而是衍生一个另外的语义，那建议用另外的句子承载。

示例：

• 正确：Python 是一种解释型语言，这意味着该语言可以直接执行源代码。（从句进一步延伸主题思想，所以从句的运用是合适的）
• 错误：Python 是一种解释性编程语言，发明于 1991 年。（从句修改了主句中的思想）

2.3 列表与表格

1. 列表与列表项

区分无序列表和有序列表。调整列表的列表项顺序不会对列表的含义产生影响时，使用无序列表。调整列表的列表项顺序会对列表的含义产生影响时，使用有序列表。

• 尽量保持列表项之间的同级 / 并列关系
• 尽量保证列表项的语法一致，逻辑层次一致，信息密度一致，标点符号一致。

另外，技术文档的有序列表项最好通过动词来开头以引导读者。

2. 表格

1. 创建表格要注意创建有意义的表头
2. 每个格子内的内容不宜过长，超过两句话的话，建议考虑拆分

3. 介绍列表和表格的技巧

推荐用一句话向用户介绍列表和表格对应的相关上下文，用冒号而不是句号来结束介绍性的句子，并在介绍的语句加上「以下」两字。

示例：

• 以下列表确定了关键性能参数：
• 下表为我方产品和竞品功能的对比数据：

2.4 段落

1. 分段落

分段落的目的是：将和主题相关的内容拆解开，再用一条顺畅的逻辑链串联起来。

2. 段首句

段首句很重要，时间紧张的读者往往只读段首句。好的段首句会建立起段落的中心思想。

3. 段落切分

每个段落只应聚焦一个主题。

段落应该展现一段独立的逻辑，并只展现这段逻辑。修改文章时，应该删掉这些和主题无关的内容，或者移动到其他段落。

另外，不应该让段落太长或太短：

• 3 - 5 个句子的段落是读者喜闻乐见的。
• 多于 7 个句子的段落就太长了。
• 整段是 1 个句子的段落也是有问题。

4. 段落三要素

好的段落回答三个问题：

• What，我们希望告诉读者什么信息
• Why，为什么这个信息对读者来说很重要
• How，读者如何运用信息，或如何向读者证实此信息

示例：

• （What）不要让段落太长。（Why）过长的段落形成了容易被读者忽略的文字墙，读者普遍喜欢三到五个句子的段落，超过七个句子的段落就容易被读者们跳过。（How）我们可以考虑将过长的段落分成两个单独的段落。
• （What）相反，也不要让段落太短。（Why）如果您的文档包含大量单句段落，那么您的组织就有缺陷。（How）我们可以考虑将过短的段落进行合并。

2.5 读者

好的文档应该提供且仅提供读者需要的信息。

好的文档 = 读者完成任务所需的知识和技能 - 读者当前的知识和技能。

1. 定义读者的角色

定义读者的角色。

定义读者的角色要注意以下问题：

• 相同角色的读者大概会具备一定程度的基础知识。不同角色的读者的知识背景可能大相径庭。
• 即使是相同角色的用户，由于专业的细分，他们对特定知识的理解程度可能也不同。
• 时间也是一个因素，大多数工程师学过代数，但由于工作中不一定使用，所以这部分知识会慢慢变得模糊。经验老到的工程师的知识也会比新工程师丰富。

示例：

该培训面向以下人群:

• 软件工程师
• 软件工程或计算机科学专业的学生
  此外，许多与工程相关的角色（例如测试和产品经理）也会从中受益。

2. 定义读者的收获

定义读者可以收获的知识或技能，以设置读者的预期。

3. 多站在读者的角度

写出一份适合读者阅读的文档需要同理心，你需要提供足够的解释来满足观众的好奇心，而非作者自己的好奇心：

• 让术语接近读者
• 妥善处理缩写
• 避免使用晦涩、抽象、冗长、或罕见的单词
• 克制文化或俗语特色
• 解释对方不一定熟悉，或一定不熟悉的上下文知识

比如对一个没有编程经验的历史系同学来说，以下单词是不容易被直接理解的：

• 语言
• 中级语言
• 汇编语言
• Python
• Java
• 程序
• C 标准库
• 分配和释放内存块
• 指针

再者，对一个 Python（但不熟悉 C 的) 程序员来说，估计难以意识到操作内存和指针的区别，所以介绍段落可以增加一些 C 和 Python 的对比。

2.6 文档内容

1. 定义范围：内容范围和读者范围

1.1 内容范围

一个好的文档会在开篇定义文档的范围，例如：这个文档介绍 XXX 系统的整体设计。

更好的文档会额外定义文档不包含的内容（这部分可能是用户期望你介绍的），例如： 这篇文章不会介绍 XXX 系统中的 AAA 项目的设计。

如有需要，声明一些前置的知识或者经验会更好，例如： 这篇文档假设你已经知晓 XXX 的派单流程。

定义范围除了帮助读者以外，还能帮助作者思考结构，使内容的组织足够聚焦。

1.2 读者范围

在前面我们也简单介绍过需要定义读者的角色，一篇好的文档会显式定义读者角色，例如：这篇运维文档是为 XXX 的运维工程师准备的。

2. 在开篇总结关键点

专业的作家会在书的第一页花极大的精力来增加读者读下去的可能性，要做好重复修改首页的准备。

对于长篇文档，提供的概要可能相当短，但我们仍然要投入精力去写。一个沉闷或者模糊的摘要会让潜在的读者失去耐心或者信心。示例：

• 模糊的摘要：本报告讨论了多个技术问题及其解决方案。
• 精确的摘要：本报告详细分析了当前网络安全面临的五大挑战，并提出了相应的解决方案。具体包括：数据加密策略、网络防火墙配置、入侵检测系统、用户权限管理和安全漏洞修复。

可以通过比较和对比的方法，利用读者已掌握的知识快速理解要义。示例：

• 直接描述：Python是一种高级编程语言，具有简洁的语法。
• 比较和对比：与Java相比，Python的语法更加简洁易懂，代码量更少。例如，同样的“Hello World”程序，在Java中需要多行代码，而在Python中只需一行：print("Hello World")。

3. 为读者写作

在前面读者部分我们介绍过相关技巧，这里进一步补充。

关于如何定义读者，我们可以思考三个问题：

• 谁是你的目标读者？
• 读者已经知道了什么？
• 阅读完文档以后，读者可以知道什么？

4. 组织文档结构

即文档大纲。

5. 模块化文档

根据实际情况，可以模块化 / 重构文档。通过模块化代码来获得更好的可读性、可维护性、复用性，文档也一样。

三、第二部分：进阶技巧

3.1 修改和审校技巧

1. 样式

参考一个成熟的样式使用指引： Highlights | Google developer documentation style guide

2. 代码

针对不同语言使用不同风格，加上代码高亮来展示。

3. 代入读者

把自己当成读者，带着目标读者的上下文读一遍文档。

4. 直接朗读

朗读文档，能帮助我们发现有没有使用不恰当的短语，冗长的句子，以及其他不自然的感觉。

5. 语气

调整语气，营造一个对话感强、友好、尊敬读者的文档氛围，尝试让自己听上去成为一个富有智识的朋友。参考 Voice and tone | Google developer documentation style guide。

3.2 组织大型文档

1. 组织形式

组织大型文档的方法有两种：

• 整合到一个大文档中
• 拆分到一批相互链接的中小文档中

如何选择组织方式，有以下几个考虑点：

• How-to 指引，介绍性总览，概念性介绍，建议用短小的文档，即拆分到一批相互链接的中小文档中
• 详细的教程、最佳实践、命令行参考，整合到一个大文档中也无妨
• 假如读者可能来回搜索，那么整合到一个大文档中会是不错的选择

2. 如何组织：大纲

设计文档的大纲，大纲帮助我们调整我们想讨论的主题的位置。

设计大纲没有定式，但可以参考下面的一些方法：

• 先告知读者为什么，再告知读者怎么做
• 无需太详细，告知读者我们要描述一个概念或完成一个任务即可
• 省略和文档主旨无关的内容，例如介绍项目的使用时，除非有特定的用意，否则可以省略项目的历史，或者通过一个外链，引导到另外一个文档
• 概念的解释和实际的运用能成对出现的话，能引起读者的兴趣

注意，假如文档需要被评审的话，那应该先草拟出大纲并评审，评审通过后再草拟其他细节内容。

3. 介绍部分的完整性和可维护性

1. 完整性。完成文档初稿后，建议检查一下文档内容是否已经准确地覆盖了文档的介绍部分提到的。
2. 可维护性：为了文档容易维护，不要在介绍部分涵盖太多细节内容。

4. 增加文档导览能力

好的文档导览元素有以下这些：

• 目录
• 介绍和总结部分
• 清晰和富有逻辑的主题发展
• 帮助用户理解主题的标题和子标题
• 指向更深入的信息的链接
• 指向其他待学习的信息的链接
• …

5. 标题下的文字部分

大部分读者希望在标题下看到文字介绍，而非直接增加一个子标题。例如：

# 创建网站
## 运行 hexo 命令
可以运行 `hexo init` 命令。命令会展示几个选项帮助你设置网站。

# 创建网站
你可以通过 hexo-client / hexo server 来创建文章和网站。

## 运行 hexo 命令
可以运行 `hexo init` 命令。命令会展示几个选项帮助你设置网站。

6. 循序渐进披露信息

注意读者接收信息的速度，避免短期介绍大量的新概念。使用以下的方式有助帮助读者理解：

• 在文档介绍部分主要介绍术语和概念
• 适度将大面积的文字拆分成表格、图标、标题
• 适度将过长的清单进行分组后拆分
• 使用简单的例子进行介绍，然后逐步增加其他的有趣或复杂的技巧
• …

3.3 插图

研究指出，为读者提供图片（无论图片的质量如何），都能提高读者对文章的好感。

当然只有有用的图片才能让读者受益。

有以下几种做法，帮助我们用图片来提高信息传达的质量：

• 先写标题，并根据标题创建插图。
• 限制一张图中传达的内容，假如整体内容太多太细，先对内容进行拆分整合，例如将复杂系统先拆分成几个子系统，介绍完子系统组成的完整系统以后，逐个介绍子系统的内部信息，可根据需要拆成多个图。
• 图中的字体样式可读性如何，对比度是否足够。比如尽量通过高亮关键信息

3.4 示例代码

好的示例代码是程序员最希望能看到的。

好的示例代码指的是：正确性，简洁性，易于理解，易于复用，包含注释，且副作用最小的代码。

1. 正确性

能够完成它声称能完成的工作，能遵循对应语言的语法规范和最佳实践，能够通过编译。

2. 简洁性

代码应该足够短，只包含最重要的部分。注意，正确性要高于简洁性。不过必要时可直接使用伪代码。

3. 易于理解

使用合适的类名、方法名、变量名定义，使用不同颜色来引导读者注意力，避免使用“深奥”的编程技巧。

4. 易于复用

很多时候，读者是希望可以得到一个可以直接使用的功能模块代码的，因此，我们应该：

• 提供读者能运行代码的充分信息，包括依赖项的信息，如何安装
• 尽量提供易于扩展或定制化的能力
• 减少副作用（你肯定不希望读者用了你的代码上线造成事故）

5. 包含注释

注释是编程必不可少的，应该：

• 控制注释的长度，注意正确性高于简洁性
• 为真正需要解释的、不直观的代码写注释，避免为显而易见的代码写注释
• 当读者已经对相关技术比较熟悉的时候，我们可以通过注释来解释为什么，而不是做什么