总结
- 时间越久，规模越大，文档越显得重要。
- 文档的变更要加入到开发人员的工作流程。
- 写文档的目标应该单一，不应该一个文档满足不同的目标。
- 明确读者是谁，而不是为了写给自己看。
google 是怎么样对待文档的
在谷歌，我们将文档视为代码并纳入开发的工作流，使工程师更容易编写和维护简单的文档。
可以看出 google 对文档的重视程度，文档和代码同级别，并且文档也和代码一样，有工作流。
写文档的好处
- 它有助于设计好的API或者架构。文档的编写本身会让工程师重新评估设计方案，否则这些方案不会受到质疑，你在写文档的时候，你本身会反思自己的设计，是否需要改进。
- 它提供了维护路线图和变更的历史记录，多年后还可以找到变更记录。
- 它使代码看起来更专业。开发人员自然会假设一个文档齐全的 API 是一个设计得更好的 API，产品是否有良好的文档通常是产品质量的一个很重要的指标。
- 它会减少别人向你提问的可能。随着时间的推移，这对于编写文档的人来说可能是收益最大的。如果你必须不止一次向某人解释某事，那么写一个文档是非常重要的，能节省你很多时间。
随着时间的推移，这些问题也可以找到答案。
- 为什么做出这些设计决策？
- 为什么我们以这种方式实现此代码？
- 如果两年后查看自己的代码，为什么我要以这种方式实现此代码？
为什么不喜欢写文档
- 因为短期收益不明显，也就是收益不会立竿见影的，尤其是对写文档的人而言，长期收益是非常明显的，因为你只写一次，会被很多人读到，但是短期收益确实不明显。
- 工程师认为写文档和写代码需要不同的技能。
- 认为自己不擅长写文档。
- 没有好的工具支持写文档。
- 文档被认为是代码之外的东西，是额外的任务，没时间。
文档开发流程
把文档与代码平等对待，可能要关注如下几个点。
- 要遵守公司内部政策或规则
- 和源代码放在一起
- 拥有负责维护文档的负责人
- 接受修改审查（并与它所记录的代码一起改变）
- 有问题（issues）可被跟踪，就像代码中的bug被跟踪一样
- 定期评估（在某些方面进行测试）
- 如果可能，对准确性、时效性等方面进行测试（还没有特别好用的工具）
明确读者
- 能力级别（菜鸟或者专家）
- 知识领域
- 目标（以 api 为例，是告诉人家怎么用api，还是告诉人家api 实现的原理）
要写哪些文档
- 参考文档，包括代码注释
- 设计文件
- 教程
- 概念文档
- 着陆页
参考文档
像 api 使用文档，是最典型的参考文档，有的语言可以用相关的格式生成，如（Javadoc、PyDoc、GoDoc），但是对于格式是有要求的，比如文件的注释，内注释，函数的注释。
文件注释
类注释
函数注释
设计文档
设计文档主要用来评审， Google 的设计文档模板要求工程师考虑其设计的各个方面，例如安全影响、国际化、存储要求和隐私问题等，在大多数情况下，这些设计文档的这些部分由这些领域的专家进行审查，一份好的设计文档应该涵盖设计的目标、实施策略，并提出关键的设计决策，并强调各自的权衡。
教程
可以理解成操作手册，比如怎么样分步搭建某一个服务。
概念文档
有些代码需要更深入的解释，而不仅仅是通过阅读参考文档就能获得的。 在这些情况下，我们需要概念文档来提供 API 或系统的概述。概念文档都是为了扩充而不是替代参考文档集。 通常这会导致一些信息的重复，但有一个目的：提高清晰度。 在这些情况下，概念文档没有必要涵盖所有边缘情况（尽管参考文献应该虔诚地涵盖这些情况）。 在这种情况下，为了清晰起见，牺牲一些准确性是可以接受的。 概念文档的要点是传达理解。
文档放在哪里
google 大部分文档都直接和源码放在一起，通过 google 开源出来的项目，会发现项目下有一个 docs 的文件夹，文件夹下面写了很多 markdown 的文档。
google 用什么格式写文档
markdown 为主，因为 markdown 可以生成网页，方便浏览与检索。
g3doc
google 有一个工具，叫做 g3doc，自己实现应该也不能。
mkdocs/mkdocs: Project documentation with Markdown. (github.com)