Google软件工程流程之文档即人品

最成功的做法是把文档当做代码，融入传统的工程工作流中，让工程师更容易编写和维护简单的文档。

高质量程齐档对工程编织作果巨大。代码和API变得更容易理解，可以减少犯错。当设计目标和团队目标在文档中有清晰的描述，项目团队就可以更好地聚焦于工作。如果步骤清晰，工程师更容易遵循步骤来手工操作流程。如果流程有清晰的文档记录，那么当新成员加入团队或者代码库时会更省事。

但是由于文档的受益者是下游用户，所以通常不会给文档作者带来直接的好处。

像代码一样对待文档。文档常常与代码紧密耦合，因此应当尽可能将其视为代码。文档应当有要遵守的内部政策或规则，置于源代码管理系统之下，有明确的责任维护主体，进行变更评审，跟踪问题，定期评估测试，对准确性有效期进行度量。

基于不同标准，读者类型有不同的分类。根据经验水平分为专家级程序员、不熟悉语言的初级工程师。根据领域知识分为团队成员、仅熟悉API端点的其他工程师。根据目的分为使用你的API执行特定任务的最终用户、负责一个特别复杂实现的软件专家。

文档类型包括以下。

参考文档:用于记录代码库内代码使用情况。代码注释是工程师必须维护的最常见的参考代码形式，包括API注释和实现注释。

设计文档:一个好的设计文档应当包含设计目标、实现策略、并提出关键的设计决策。最好的设计文档会给出建议的设计目标并包含设计替代方案及其优缺点。

新手教程:按顺序执行的步骤，显式地为这些步骤编号。没有什么比在第四步出错更让人恼火的了，比如，你忘记告诉人们正确授权他们的用户名。

概念文档:有些代码需要比阅读参考文档更深入的解释或理解。我们需要概念文档来提供API或系统的概述。

着陆页面:一个典型的着陆页面可能包含一些有趣的链接，有时可能包含几个首先阅读这里的文档。

技术文档有三种不同的评审类型，每种方式的关注点不同。

技术评审，保证文档的准确性。

读者文档，保障文档的清晰度。

写作评审，保证文章的一致性。

文档的五个W:Who即文档的受众，What即文档的功能，When即文档的创建维护时间，Where即版本控制，Why即设置该文档的原因。

文档的开头中间和结尾:第一部分描述问题，中间部分是建议的解决方案，结尾是总结出的结论。

优秀文档的三要素:完整性、准确性、清晰性。

在时间和规模维度上，文档都非常重要。文档变更应当利用现有的开发人员工作流。保持文档聚焦一个目的。为你的读者而不是你自己编写。