摘要

本文主要是结合作者的项目实践来说明文档对于一个团队开发的重要性, 以及在提高效率节省时间方面的意义, 并且指出如何在实践开发中写文档与维护文档.

引入

请先思考下面几个问题:

1. 如果你是刚加入一个项目组的新手,你能够看到你们项目的相关文档吗?你希望看到吗?
2. 如果你是一个架构师,或者高级程序员, 你经常会被其他同事询问相关的架构问题吗?你会千百遍地回答同一个问题吗?
3. 你是如何写文档的呢? 你为哪些内容些文档呢? 你是如何管理文档的呢? 你如何保证文档与代码同步呢?

如果你思考这些问题时,只是不住地在摇头, 那么, 是你为自己的项目写文档或者要求团队成员建立文档系统的时候了.

为什么要写文档

其实原因很简单, 1) 为新手提供一个快速入门的路径 2)为自己节省大量的宝贵时间 3)为项目赢得更多的开发时间 4)在一个high-level的层次 提供项目的一个审视角度(code是low-level)

如果你还在耐心而细致地为自己团队新加入的成员解释开发环境如何配置, 整个开发框架, 或者整个团队的构成等, 我在对你的 耐心保持钦佩的同时,也在心里责备你的低效(如果我是你的leader, 我可不希望你把时间老是花在教导新手上).

为什么大多数程序员都不喜欢写文档

相比于编码和开发, 那种相应而生的结果会给你不断带来一些欣喜和成就感, 而写文档, 很枯燥, 它只是一些文字的堆积,不会 让项目进展向前, 也不会让你在自己负责模块中去掉一条todo. 这就是成就感的问题.

更让人烦恼的是, 你的代码可能会不断重构, 框架也会不断修改, 代码的注释你很自然地随之更新,而文档你又懒得去动了, 但是不动, 又不能反映最新的代码和框架, 不仅不能帮助阅读文档的同事,更甚会让他们"误入歧途", 于是你无奈地去更新了文档, 在更新中 你发誓不再写这些文档了. 这就是维护的问题.

或者更偏激地说,有部分的程序员更是不乐意将框架或者自己的经验写成文档(我想这是少数的), 因为他盘算自己一路走过的艰辛, 到后来就认为这种无文档死磕代码的过程是必须的, 也就心安理得地去看着新手在荆棘中前行. 这是心态的问题.

还有一部分程序员, 他们认为自己是没有能力写文档,或者说是没有到写文档的水平, 虽然自己会用现在的框架,但是又弄不清楚, 它的实现,及其相应的数据交互和设计理念等. 他怕写出的文档会误导别人,怕"出洋相". 这就是思路的问题.

等等,可能还有其它的原因.

为什么我们应该去写文档呢

那么,我来逐条地分析你不写文档是不对的.

1. 成就感: 个人认为, 一天写的code越少, 思考的时间, 写文档的时间越多, 正是说明了你能力的提升, 说明了你心中有big picture, 而 不再只拘泥于去实现一个feature, 一个功能. 思考是为了写出更好的代码, 写文档是为了更好支持后续的代码维护和对新手的关怀. 你的新同事当看到你写的文档时,他会打心眼里感激你的.你的老板在看到你条理清楚的文档时, 他会考虑提拔你的. 想必你也知道项目经理的 工作不再专注于代码,而是文档(需求文档,开发文档等). 所以,在写文档时,你要自信,你更要觉得有更高的成就感.
2. 维护: 文档的更新肯定是滞后于代码的更新的, 所以要保持文档的正确和准确,就必须有一定的机制来保证文档也是最新的. 经过实践证明,使用 wiki这样的系统来维护文档是比较合适而且高效, 因为:
   • wiki本身的一个特点就是 不断变化更新的 , 所以其他同事会知道, 这些文档会不断更新,我要不断tracking
   • wiki内置的版本控制,也会很方便文档的撰写与分享
   • wiki本身的协作机制,也会让维护起来更加方便(想想wikipedia,有哪篇文章是一个人一次性完成的)
3. 心态: 分享不只是一种行为而且是一种精神, 当你看到本篇博客时, 我正在分享, 当你看完后写一个留言时,你也在分享. 分享是互联网的基石, 也是知识价值最大化的体现.如果你还想或者以为自己的过去的艰辛也希望别人同样经历, 我想我不会看好你的未来,我也不希望和你成为朋友, 而这些行为 本身也不能让你获益多少.保守而封闭的思路,则会 影响到你所能达到的level. 我们在努力工作,努力学习的每一天都是希望我们自己以后的子女不再这么辛苦, 那何尝不可以将"子女"扩大到 每一个人呢?将知识分享给朋友, 分享给他人, 你也会得到别人的认可与支持, 当然他们也会回馈给你他们的心得与体会. 分享的路上你并不孤单.
4. 思路: 首先认为自己没有能力或者水平写文档的程序员都是有着错误的思路, 因为 没有人能够保证他写的都是正确的, 即使是 Donald Knuth 大牛. 你写出的东西, 你的同事看了, 在获益的同时,倘若发现的问题,他并不会责备你, 而会怀着感激与讨论的心态来与你交流,最终你也许就纠正了 自己的错误, 从而成长起来. 如果你不去分享,也许你一辈子都不会明白,"哦,原来应该是这样". 写出自己的思路, 写出自己的认识, 与别人分享,帮助别人, 也提高自己.

当然,大道理谁都会说,关键行动还在于你自己.

回到一个比较关键的问题, 就是究竟该如何写文档, 哪些应该写,哪些不应该写.

如何写文档

在写文档前,你得思考,要写哪些内容, 我总结如下:

1. 项目中关键处理逻辑

   • 使用的框架
   • 整个处理过程(譬如点击一个link或者button后,后续的完整处理流程和交互逻辑)

2. 规范性内容(如编码规范,文档规范, 注释规范等等)

3. 知识性内容(如某个工具的使用方法, 某个插件如何提高开发效率等)

4. 经验性东西(如一些最佳实践, sql如何写, 如何保证代码的可复用性等)

5. 教程性内容(如如何让一个新手使用当前的框架写出一个功能等,如何让他快速入门)

6. FAQ类似的内容(当你被同事或者客户同一个问题问了超过3遍时,你就应该写出文档来, 来避免再次被占用这宝贵的程序员时间)

当然上面提到的都是开发相关的文档, 也是我们每个程序员可能要写的. 还有几类文档, 如需求文档, 开发文档, 测试文档, 用户文档等, 也可能需要程序员参与.

除此而外,另一大类,就是代码的API, 这类文档最好的处理方式是自动化, 如 doxygen, epydoc 等一系列工具. 使用这样的工具, 可以免去重新写API的文档,只需要自动生成即可, 而后续如果代码和注释有更动,也只需要重新生成即可.

解决了写哪些内容, 我们来看,如何去与文档, 如何去维护文档.

这里有个参考: How to make documents evolve?

我经历过的团队, 有不写文档的, 有写文档但是经常会过时的, 也有维护较好的. 根据我个人的经验,我的建议是:

使用一个良好组织的wiki来作为文档管理系统, 对于项目中的文档中及时更新, 保证是准确和正确的.

当然,如果你不想去维护一个文档系统, 那么宁可不要文档, 因为 错误的文档还不如没有文档.

那么文档放在哪里合适呢?

个人建议是与代码一起纳入版本控制系统,如我在 你使用源码管理工具吗? 中推荐的 bitbucket, 中集成有wiki. 这样维护和更新起来都会比较方便.

结论

文档是一个公司实力的体现,也是管理者素质和能力的体现, 它对于开发者是极大的财富.所以维护一个良好组织的文档, 不仅能够在开发中让你获益无数, 而且在提高成员对团队的认可度,对公司的忠诚度等方面也会有很大的提升.

如果你们团队还没有文档,现在就开始写吧.

后记

还记得自己曾经在加入一个团队时, 得到的只是一个svn账号, 一个任务说明, 然后就是deadline. 而且我们是远程的, 没有更多的交流机会. 当时那接下来的几天,真是暗无天日, 我生生地在读代码, 做梦企盼天上能掉下来一个文档. 经过艰苦卓绝的努力, 一周后,还是弄清楚了整个框架和思路, 我便写了一个文档, 不希望后面的同事也和我经验同样的苦痛与无助.

参考资料

1. How to make documents evolve?
2. Donald Knuth

本文的rst源码

本文的源码链接在 这里 .

点击 下载pdf阅读 (如果浏览器不支持直接打开,请点击右键另存)