谷歌的软件工程 读书笔记（十）文档

码农的两大烦恼：

1. 别人的代码没有文档
2. 别人居然要求我给我的代码写文档

文档的质量差，数量少，甚至根本没有文档是软件工程面临的普遍问题。

什么是合格的文档？

任何对于代码的补充性文本都是文档，包括代码的注释。

为什么需要文档？

文档对于作者而言往往无法马上带来直接收益，然而就像测试一样，投资到文档里的投入最终往往会带来丰厚的回报。文档会拥有成千上万的读者，它一般会帮助回答以下的问题：

码农对于文档的轻视除了不能带来短期收益外，还有如下的原因：

好的文档收益如下：

文档就像代码

文档和代码一样，需要保持清晰，准确，一致，避免出错。文档需要有维护者和所有者。

谷歌使用go/links来使文档的访问变得简单。

文档和代码仅仅的耦合，所以应该被看作是代码的一部分。

文档应该：

了解你的读者

工程师写文档犯下的最大的错误就是以为文档是写给自己看的。记住写文档的时候要清楚的了解谁才是这个文档的读者。不一定要写出完美无暇的文档们，但是要写出适合读者阅读的文档。

需要考虑读者的不同方面

文档的类型

文档的类型包含：

文档的审视

文档和代码一样，需要审视。

文档的审视需要考虑以下的内容：

写文档的哲学

什么时候需要技术写作者？

技术写作者（technical writer）并不意味着工程师就不用写文档了，他们可以从另一个角度来看待你的项目，作出一样的假定。这一点非常重要。

总结

和测试相比较，文档在谷歌受到的重视程度还是要低一些。测试可以自动化，而文档不可以。

要解决文档的问题，工程师和其组织必须承认，他们即是问题，也是解决方案。写好文档是工作的一部分。而这些文档会存在很长时间，被很多人阅读。好的文档不仅仅帮助那些阅读它的人，也会帮助他的作者。

来源：闻数起舞