转载

文档那些事儿

还记得在2008年我做毕业设计的时候，自己心里有一个朦朦胧胧的概念，大概是说，要规范，制度上有标准，流程上有遵循。于是噼里啪啦整了软件工程十项文档，再加上一些辅助性文档就有了下面这个清单。我以为那样的全面会带来更好的评价，但是老师说，“太多了”，我很困惑，难道文档全面、综合，而且完备，这不好么？

文档那些事儿

在Amazon有一个大家都知道和反复自黑的事情。所有team都用wiki来记录和维护项目、产品有关的事情，但是绝大多数wiki的内容都是过时的和不准确的。有几次和其他互联网公司的朋友讨论过这个话题，大家都付诸呵呵一笑，原来大家都差不多。这让我思考，是不是文档这样的东西，和代码不同，它更容易过时，它更难以融入现代软件开发的流程中去？

要是早些年，我可能还很乐于见到那些鼓吹方法论的敏捷咨询师们，跳出来讲：来，看看我的敏捷实践，我们需要怎样怎样清晰简单的文档，我们不需要如何如何复杂冗余的设计。但是现在我越来越觉得，对于工程师来说，文档和代码从根上的不同，让前者同后者一样保持新鲜和完备，不是一件能够自然和遵循工程规律的事情。

如果我改变了一个特性，负责的工程师会完善代码，更新测试用例，并且跟进代码审查。但是很少有工程师会记得去把文档更新和补充完全。项目计划的时候，scrum的时候，如果说，“花一天时间来完善文档”，这听起来有点不那么充实啊。文档的地位，总让人觉得不那么正派而光明磊落。

在我前一家公司，项目流程更加严格和正统，于是文档流程也更加规范。很多公司都设有technical writer的职位，他们比工程师更善于归纳、总结文字。但即便如此，大多数文档还是过时的，因为他们更多地负责跟进项目的重要文档，以及对外发布的文档，内部的大大小小资料那么多，不可能有暇顾及。我不知道除了互联网的wikipedia这种方式以外，还有什么好的模式能让大家都参与进文档的编辑活动，保证大多数内容保持更新？个中的林林总总，我猜想工程师应当是不甚有兴趣的吧。

项目经理和团队经理往往关心这一点，相应的文档是否得到更新？指南、说明，以及数据结果。解决了一个问题，能否总结成条文记下来。一切都以防等到哪天工程师挂了，可以拉一个来顶上。但实际呢？“蜡烛点点亮亮”，指望工程师去主动做并做好这些事，是很难的。而且，一个劲地去整文档的事情，那多没趣啊，一点都不酷啊，不是吗？

“只有代码永不过时”。

这是我的信条。只有文档融合在代码里的时候，它才能得到最佳的维护。举例来说，Javadoc或者JSDoc都可以通过脚本来生成最终的API手册。而本身它们的存在形式——注释，就是非常贴近代码本身和容易得到审查更新的。除了文字，图片、视频等其它多媒体形式也可以作为注释的一部分嵌入代码，只是很少人如此实践而已。

另一方面，文档要简约而有效。如今我参与的项目，无论大小，主要文档只有一篇wiki，讨论开会之前花10分钟基本都可以阅读完成。代码，以及代码注释，甚至包括代码包中的readme.md文件，能够清晰表达出来的内容，就不要再在文档中冗余。面对工程师的时候，RTFC（Read The Fucking Code）应当比RTFM更具鼓动性和说服力。

原文 http://www.raychase.net/4083

正文到此结束