你写文档吗?你为什么应该写文档?本博客所有内容采用 Creative Commons Licenses 许可使用. 引用本内容时，请保留 朱涛, 出处 ，并且 非商业 . 点击 订阅 来订阅本博客.(推荐使用 google reader, 如果你的浏览器不支持直接订阅,请直接在 google reader 中手动添加). 点击 下载pdf阅读 (如果浏览器不支持直接打开,请点击右键另存) 引入请先思考下面几个问题:
如果你思考这些问题时,只是不住地在摇头, 那么, 是你为自己的项目写文档或者要求团队成员建立文档系统的时候了. 为什么要写文档其实原因很简单, 1) 为新手提供一个快速入门的路径 2)为自己节省大量的宝贵时间 3)为项目赢得更多的开发时间 4)在一个high-level的层次 提供项目的一个审视角度(code是low-level) 如果你还在耐心而细致地为自己团队新加入的成员解释开发环境如何配置, 整个开发框架, 或者整个团队的构成等, 我在对你的 耐心保持钦佩的同时,也在心里责备你的低效(如果我是你的leader, 我可不希望你把时间老是花在教导新手上). 为什么大多数程序员都不喜欢写文档相比于编码和开发, 那种相应而生的结果会给你不断带来一些欣喜和成就感, 而写文档, 很枯燥, 它只是一些文字的堆积,不会 让项目进展向前, 也不会让你在自己负责模块中去掉一条todo. 这就是成就感的问题. 更让人烦恼的是, 你的代码可能会不断重构, 框架也会不断修改, 代码的注释你很自然地随之更新,而文档你又懒得去动了, 但是不动, 又不能反映最新的代码和框架, 不仅不能帮助阅读文档的同事,更甚会让他们"误入歧途", 于是你无奈地去更新了文档, 在更新中 你发誓不再写这些文档了. 这就是维护的问题. 或者更偏激地说,有部分的程序员更是不乐意将框架或者自己的经验写成文档(我想这是少数的), 因为他盘算自己一路走过的艰辛, 到后来就认为这种无文档死磕代码的过程是必须的, 也就心安理得地去看着新手在荆棘中前行. 这是心态的问题. 还有一部分程序员, 他们认为自己是没有能力写文档,或者说是没有到写文档的水平, 虽然自己会用现在的框架,但是又弄不清楚, 它的实现,及其相应的数据交互和设计理念等. 他怕写出的文档会误导别人,怕"出洋相". 这就是思路的问题. 等等,可能还有其它的原因. 为什么我们应该去写文档呢那么,我来逐条地分析你不写文档是不对的.
当然,大道理谁都会说,关键行动还在于你自己. 回到一个比较关键的问题, 就是究竟该如何写文档, 哪些应该写,哪些不应该写. 如何写文档在写文档前,你得思考,要写哪些内容, 我总结如下:
当然上面提到的都是开发相关的文档, 也是我们每个程序员可能要写的. 还有几类文档, 如需求文档, 开发文档, 测试文档, 用户文档等, 也可能需要程序员参与. 除此而外,另一大类,就是代码的API, 这类文档最好的处理方式是自动化, 如 doxygen, epydoc 等一系列工具. 使用这样的工具, 可以免去重新写API的文档,只需要自动生成即可, 而后续如果代码和注释有更动,也只需要重新生成即可. 解决了写哪些内容, 我们来看,如何去与文档, 如何去维护文档. 这里有个参考: How to make documents evolve? 我经历过的团队, 有不写文档的, 有写文档但是经常会过时的, 也有维护较好的. 根据我个人的经验,我的建议是: 使用一个良好组织的wiki来作为文档管理系统, 对于项目中的文档中及时更新, 保证是准确和正确的. 当然,如果你不想去维护一个文档系统, 那么宁可不要文档, 因为 错误的文档还不如没有文档. 那么文档放在哪里合适呢? 个人建议是与代码一起纳入版本控制系统,如我在 你使用源码管理工具吗? 中推荐的 bitbucket, 中集成有wiki. 这样维护和更新起来都会比较方便. 结论文档是一个公司实力的体现,也是管理者素质和能力的体现, 它对于开发者是极大的财富.所以维护一个良好组织的文档, 不仅能够在开发中让你获益无数, 而且在提高成员对团队的认可度,对公司的忠诚度等方面也会有很大的提升. 如果你们团队还没有文档,现在就开始写吧. 后记还记得自己曾经在加入一个团队时, 得到的只是一个svn账号, 一个任务说明, 然后就是deadline. 而且我们是远程的, 没有更多的交流机会. 当时那接下来的几天,真是暗无天日, 我生生地在读代码, 做梦企盼天上能掉下来一个文档. 经过艰苦卓绝的努力, 一周后,还是弄清楚了整个框架和思路, 我便写了一个文档, 不希望后面的同事也和我经验同样的苦痛与无助. |
|
|
