文档那些事儿

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

文档那些事儿

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

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

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

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

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

“只有代码永不过时”。

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

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

文章未经特殊标明皆为本人原创,未经许可不得用于任何商业用途,转载请保持完整性并注明来源链接《四火的唠叨》

分享到:

3 comments

  1. Skywalker 说道:

    文档融入代码是一种保证文档up to date的方法,
    另外也可以看下TDD,测试驱动文档。

  2. 大头龙仔 说道:

    严重同意!包括后面说的,文档应该是融进代码里,注释,框架约定等

  3. Abner 说道:

    的确如此,最好的是连注释都不需要。

Abner 进行回复 取消回复

电子邮件地址不会被公开。

您可以使用这些 HTML 标签和属性: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>