google 写技术文档的标准

Posted on | Post modified:
google的一篇介绍怎么构造技术文档的整理

google 写技术文档的标准

定义一个全新或者不熟悉的专业词汇

  • 如果这个词汇已经被人定义过，可以给文档中加入一个完整描述的链接
  • 如果文档中对专业词汇定义很多，需要给出一个完整的词汇列表

一致性

在文档中，对一个专业词汇要保持一致的写法

  • 错误的示范
    Protocol Buffers provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

  • 正确的示范
    Protocol Buffers (or protobufs for short) provide their own definition language. Blah, blah, blah. And that's why protobufs have won so many county fairs.

    缩写词的使用

TTN = Telekinetic Tactile Network

  • 如果缩写词不是特别长，例如MapReduce没必要使用MR来定义

  • 在文档中使用缩写词，需要在第一次使用的时候，使用完整，并用括号来包裹缩写词

    This document is for engineers who are new to the Telekinetic Tactile Network (TTN) or need to understand how to order TTN replacement parts through finger motions.

代词的使用

主要在于上一个语句中的短语太多，代词不能清晰得指向具体是哪一个

You may use either Frambus or Foo to calculate derivatives. This is not optimal.

使用主动语态代替被动语态

Active Voice Sentence = actor + verb + target
Passive Voice Sentence = target + verb + actor
主动语态更能让人明确actor的主导

  • 主动语态：The cat sat on the mat.
  • 被动语态：The mat was sat on by the cat.

使用强动词来加深理解，避免弱动词的使用

  • 强动词例子： The error occurs when clicking the Submit button.
  • 弱动词例子： Clicking the Submit button triggers the error.

这个和上面讲的被动语态有一点重叠，主要在于需要加深读者的印象

尽量少使用there is/there are

  • There is a variable called met_trick that stores the current accuracy.
  • 替换为A variable named met_trick stores the current accuracy. The met_trick variable stores the current accuracy.明显更加清晰

减少一些形容词和副词的使用

  • Setting this flag makes the application run screamingly fast.
  • 替换为Setting this flag makes the application run 225-250% faster.更加清晰明确

使用短小的句子来表达

和维护代码类似，短句能带来更多的优势

  • 更加清晰，方便阅读
  • 方便维护(修改)
  • 文档中额外的部分导致的歧义也会更多

和写代码类似，使用break和continue来减少长语句，比如使用1,2,3或者直接是小圆点，分段表达

  1. 减少子语句，一个语句只表达一个观点就行，I prefer to code in C++ because I like strong data typing.可以切成两个
  2. 减少引起子语句的词(which, that），这里有个小提示，对于美国人来讲，使用which标识前后两个语句需要一点暂停，而使用that则不需要

使用列表和表格

列表

  • 无序列表，每一行都可以抽出来，并不影响剩下的行表达的意思
  • 有序列表，代表是有一定紧密联系的，抽出任意一行，都会影响到其他行的意思
  • 嵌入式列表(也就是一行语句中包含了多个独立单词的意思)，这里并不提倡使用这种方式来写技术文档 The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicugnas, and track dromedaries.

对于列表来说，列表中的每一个元素都应该是格式完全一致的
例如都是一个完整的句子（首字母要大写都大写，都使用同一个语态)，都是一个单词等

表格

  • 和列表类似，表格也需要突出每一列的数据都应该是同一个格式和类别
  • 不要在一个单元格中放入太多的字段

段落

  • 每一个段落中都应该有明确的中心思想
  • 每一个段落都应该表达一个明确的主题，不要在一个段落中引入其他段落的意思，容易给读者造成混淆
  • 不要使用一句话的段落，使用短句来表达。

一个好的段落应该包含以下方面：

  1. 这个段落具体要讲什么
  2. 对于读者的重要性在什么地方
  3. 读者怎么认同这个观点

面向的受众

技术文章里的一些词汇都比较专业，如果给一个不是很熟悉的人来阅读，那么会造成读者很大的困扰。因此，你的技术文章如果技术性比较强，那么你需要列举出能读懂你这篇文章的前提条件是什么

  • 决定你的受众（技术人员，设计人员,)
  • 你的受众需要掌握的知识(java, python, c,)
  • 使用简单的词汇来表达准确的含义，不要使用成语，俚语等只有一部分人知道意思的词汇

文档

  • 明确指出文档内容涉及到的范围
  • 指定所限的受众体
  • 文档要在前面就明确指出你这篇文档的关键点
  • 把你的话题拆成几部分，每一部分能让读者了解到一个具体的事物(完成一项具体的小任务这种)

google writing style