本文大部分内容翻译总结自《Software Engineering at Google》 第10章节 Documentation。 首先声明,本问所说的文档不仅限于纯文本文档,还包含代码注释(注释也是一种特殊形式的文档)。
很多技术人自己非常轻视技术文档的书写,然而又时常抱怨文档不完善、质量差、更新不及时…… 这种在程序猿间普遍存在的矛盾甚至已经演变成了一个段子。
文档的重要性
高质量的文档对于一个组织或团队来说有非常多的益处,比如让代码和API更容易理解、错误更少;让团队成员更专注于目标;也可以让一些手工操作更容易;另外如果有新成员加入的话有文档也会让他们更快融入……
写文档有比较严重的收益滞后性,不像测试,你跑一个测试case,它能立即告诉你是对还是错,它的价值马上就体现出来了。而写一份文档,随着时间的推移,它的价值才会逐渐体现出来。 你可能只写一次文档,将来它会被阅读上百次、上千次,因为一份好的文档可以在未来替你向别人回答类似下面这些问题。
- 为什么当时是这么决策的?
- 为什么代码是这样实现的?
- 这个项目里都有哪些概念?
- ……
写文档同样对于写作者也有非常大的收益:
- 帮你构思规范化API: 写文档的过程也是你审视你API的过程,写文档时会让你思考你API设计是否合理,考虑是否周全。如果你没法用语言将API描述出来,那么说明你当前的API设计是不合理的。
- 文档也是代码的另一种展现: 比如你两年后回过头来看你写过的代码,如果有注释和文档,你可以很快速理解代码。
- 让你的代码看起来更专业: 我们都有个感觉,只要文档齐全的API都是设计良好的API,虽然这个感觉并不完全正确,但这两者确实是强相关的,所以在很多人眼里,文档的完善度也成为衡量一个产品专业度的指标。
- 避免被重复的问题打扰: 有些问题你只需要写在文档里,这样有人来问你的时候你就可以让他直接去看文档了,而不是又给他解释一遍。
为什么大多数人都不喜欢写文档?
关于文档的重要性&