Google 是怎么样写文档的

总结

  • 时间越久,规模越大,文档越显得重要。
  • 文档的变更要加入到开发人员的工作流程。
  • 写文档的目标应该单一,不应该一个文档满足不同的目标。
  • 明确读者是谁,而不是为了写给自己看。

google 是怎么样对待文档的

在谷歌,我们将文档视为代码并纳入开发的工作流,使工程师更容易编写和维护简单的文档。

可以看出 google 对文档的重视程度,文档和代码同级别,并且文档也和代码一样,有工作流。

写文档的好处

  • 它有助于设计好的API或者架构。文档的编写本身会让工程师重新评估设计方案,否则这些方案不会受到质疑,你在写文档的时候,你本身会反思自己的设计,是否需要改进。
  • 它提供了维护路线图和变更的历史记录,多年后还可以找到变更记录。
  • 它使代码看起来更专业。开发人员自然会假设一个文档齐全的 API 是一个设计得更好的 API,产品是否有良好的文档通常是产品质量的一个很重要的指标。
  • 它会减少别人向你提问的可能。随着时间的推移,这对于编写文档的人来说可能是收益最大的。如果你必须不止一次向某人解释某事,那么写一个文档是非常重要的,能节省你很多时间。

随着时间的推移,这些问题也可以找到答案。

  • 为什么做出这些设计决策?
  • 为什么我们以这种方式实现此代码?
  • 如果两年后查看自己的代码,为什么我要以这种方式实现此代码?

为什么不喜欢写文档

  • 因为短期收益不明显,也就是收益不会立竿见影的,尤其是对写文档的人而言,长期收益是非常明显的,因为你只写一次,会被很多人读到,但是短期收益确实不明显。
  • 工程师认为写文档和写代码需要不同的技能。
  • 认为自己不擅长写文档。
  • 没有好的工具支持写文档。
  • 文档被认为是代码之外的东西,是额外的任务,没时间。

文档开发流程

把文档与代码平等对待,可能要关注如下几个点。

  • 要遵守公司内部政策或规则
  • 和源代码放在一起
  • 拥有负责维护文档的负责人
  • 接受修改审查(并与它所记录的代码一起改变)
  • 有问题(issues)可被跟踪,就像代码中的bug被跟踪一样
  • 定期评估(在某些方面进行测试)
  • 如果可能,对准确性、时效性等方面进行测试(还没有特别好用的工具)

明确读者

  • 能力级别(菜鸟或者专家)
  • 知识领域
  • 目标(以 api 为例,是告诉人家怎么用api,还是告诉人家api 实现的原理)

要写哪些文档

  • 参考文档,包括代码注释
  • 设计文件
  • 教程
  • 概念文档
  • 着陆页

参考文档

像 api 使用文档,是最典型的参考文档,有的语言可以用相关的格式生成,如(Javadoc、PyDoc、GoDoc),但是对于格式是有要求的,比如文件的注释,内注释,函数的注释。

文件注释

20

类注释

20

函数注释

20

设计文档

设计文档主要用来评审, Google 的设计文档模板要求工程师考虑其设计的各个方面,例如安全影响、国际化、存储要求和隐私问题等,在大多数情况下,这些设计文档的这些部分由这些领域的专家进行审查,一份好的设计文档应该涵盖设计的目标、实施策略,并提出关键的设计决策,并强调各自的权衡。

教程

可以理解成操作手册,比如怎么样分步搭建某一个服务。
20

概念文档

有些代码需要更深入的解释,而不仅仅是通过阅读参考文档就能获得的。 在这些情况下,我们需要概念文档来提供 API 或系统的概述。概念文档都是为了扩充而不是替代参考文档集。 通常这会导致一些信息的重复,但有一个目的:提高清晰度。 在这些情况下,概念文档没有必要涵盖所有边缘情况(尽管参考文献应该虔诚地涵盖这些情况)。 在这种情况下,为了清晰起见,牺牲一些准确性是可以接受的。 概念文档的要点是传达理解。

文档放在哪里

google 大部分文档都直接和源码放在一起,通过 google 开源出来的项目,会发现项目下有一个 docs 的文件夹,文件夹下面写了很多 markdown 的文档。

20

google 用什么格式写文档

markdown 为主,因为 markdown 可以生成网页,方便浏览与检索。

g3doc

google 有一个工具,叫做 g3doc,自己实现应该也不能。

mkdocs/mkdocs: Project documentation with Markdown. (github.com)

srecon16europe_slides_macnamara.pdf (usenix.org)

gvisor/g3doc at master · google/gvisor (github.com)

发表评论