Google 《Technical Writing 1》技术文档

词语

• 定义专业术语。

  如果已有专业术语，提供专业术语的链接。新术语需要提供定义。如果文档术语较多，需要提供附录。

• 保持一致。

  使用了某个形式的术语，之后都要保持一致。比如 Protocal Buffers，如果使用了protobufs指代，即往后都需要使用 protobufs。

• 恰当使用缩写。

  段落中使用了缩写，往后也要使用缩写，不要来回在全程和缩写之间来回切换。

• 何时使用缩写。

  如果文档中频繁出现某个术语，或者全称极度长。

• 代词。

  不中途切换代词指代。

主动语态

技术文档绝大部分情况应该尽可能使用主动语态。区分主动语态和被动语态：

主动语态：

主动语态 = 操作者(Actor) + 动作 + 目标  // 例子：猫坐在垫子上

被动语态：

被动语态 = 目标 + 动作 + 操作者(Actor)   // 例子：垫子被猫坐在上面

祈使词语可以省略操作者(Actor)，比如： 『打开 package.json 文件』

使用主动语态的好处：

• 读者心智上不需要在这两者之间来回切换。
• 被动语态不直观
• 主动语态通常更简短

简明的句子

技术文档不是营销文案，尽可能减少不必要的形容词和副词。

例子：

开了这个选项让应用极其快。

改为：

开启这个选项让应用快 225-250%。

简短的句子

和编码一样，使用简短句子的文档好处是：

• 更加容易看懂

• 更加容易维护

• 更加不容易出错

• 一个句子只说一件事情

  例子：1950年后期为编程语言的重要时期是因为IBM发行了Fortran和次年John McCarthy发明了Lisp，这让程序员可以以迭代或者递归来解决问题。

  改进后：1950年后期是编程语言的重要时期。IBM在1957年发行了Fortran。随后次年John McCarthy发明了Lisp。所以，在1950年后期，程序员可以通过迭代或者递归来解决问题。

• 把长句转成列表

  例子：更改循环体可以：

1. break, 退出整个循环
2. continue，停止当前迭代，继续下一个迭代

• 排除或减少冗余的词语

列表和表格

列表分为几种：

• 无序列表（Bulleted Lists）
• 有序列表（Numbered Lists）
• 行内列表（Embedded Lists）

使用无序列表，更改条目的顺序不影响整个列表的逻辑。相反，使用有序列表的时候更改顺序影响列表的逻辑。

例子：

无序列表：Bash 提供以下处理字符串的功能：

• 从字符串的开始删除子串
• 读取整个文件到一个字符串变量

有序列表：通过一下步骤重新配置服务器：

1. 停止服务器
2. 编辑配置文件
3. 重启服务器

行内列表：列表分为无序列表、有序列表和行内列表。

总的来说，行内列表用于技术文档比较不那么地友好，尽可能把行内列表转换成有序或者无序列表。

并联列表项

列表项尽可能表达平级、相似的意思，比如：

• 胡萝卜
• 青菜
• 土豆

而不是：

• 胡萝卜
• 青菜
• 夏天的太阳

有序列表使用命令式的动词开始

1. 下载 VSCode.app (https://code.visualstudio.com/download)
2. 移动下载内容到 /Applications 目录下
3. 打开 VSCode.app

创建可用的表格

表格在段落中暂时很容易就能获取注意力。

段落

• 开门见山
• 一个段落一个话题
• 不要太长或太短
• 包含 What ，Why 和 How

受众

好的文档 = 你的受众完成某个任务需要知道的知识技能 - 你的受众现有的知识技能

换句话说，要做到这点：

1. 定义你的受众

   首先确定你的受众的角色（role），比如有：

• 软件工程师
• 技术人员（非软件工程师，比如技术经理）
• 专家
• 学生
• 应届生
• 非技术职位

1. 确定你的受众将学会什么

   列一个清单表明受众需要要完成的目标：

   阅读该文档后，你应该能做到：
   * 使用 Zylmon API 列举旅馆的价格
   * 使用 Zylmon API 列举旅馆的地址
   * 使用 Zylmon API 列举用户评分
   
   

   如果是编写设计文档，则列举受众将会知道的知识点：

   阅读该文档后，你应该能知道：
   * Zylmon 打败 Zyljenue 的三个原因
   * Zlymon 花费 5.25 人年工程量开发的五个原因
   
   

2. 根据以上情况调整文档

   • 专业词汇和概念
   • 专家盲点（Curse of knowledge）- 指一旦学会了某种复杂的概念，就丧失了对别人解释这个概念的能力

   [图片上传中...(image-38d119-1601351217806-0)]

   总结

• 使用术语要一致
• 避免有歧义的代词
• 尽量使用主动语态，而不是被动语态
• 选择准确而不是模糊的动词
• 一句话说一件事情
• 把长句转换成列表
• 消除不必要的词语
• 顺序相关时候使用有序列表，不相关则使用无序列表
• 列表条目要对等
• 在有序列表开头使用命令式词语
• 段落开头使用中心句
• 一个段落一个话题
• 确定受众将会学到什么
• 文档为受众服务
• 在开头建立文档的中心点