敏捷开发学习总结: 思考开发文档的利与弊
文档是个好东西，这是不可否认的，但是太依赖文档也有弊端，下面我从不同的度来分析一下文档的利与弊，然后思考在敏捷开发时，文档又是如何进行的。
从 公司的角度来看，编写文档有如下好处：
a1) 公司使用的是瀑布生命周期（或序列式开发，传统开发），所以必然的，在某一个阶段，需要编写大量的文档作为进入下一阶段的输入。
a2）过程改进的 需要，认为只要过程控制得足够细，例如只要文档编写得足够详细，那么人员是可以被替换的，也就是说，有了文档，人员的流动不会给项目带来大的风险。
a3） 受到其它行业的启示，例如建筑行业，图纸制定好并确否没有问题后，施工队才能准确无误地施工，所以要求在编码之前先编写HD、DD文档,除了方便交叉 REVIEW，同时，文档用于指导资浅工程师的编码工作，文档只有编写的足够详细(DD最好给出伪代码)，工程师才不至于走偏。
a4) 企业知识库的建设需要，没有文档，技术就没有得到积累。
从工程师的角度来看，为什么工程师有时不愿意写文档呢？
b1） 代码与文档的同步问题，很多设计文档在写完后就被代码远远地抛在后面了，开发人员只有二个选择，要不更新文档，要不任由文档逐渐地开始撒谎，如果选择维护 文档与代码同步，那么就会耗费大量的时间和精力在文档更新上面，而维护这份文档目的只是为了将来有可能有人需要阅读---也有可能无人问津。
b2） 任务的工时安排得很紧，但编写文档又导致进度太慢。
b3）认为文档太枯燥，不比编写代码有成就感。
b4）没自信，怕文档写不好会误导别 人。
b5）本身没有搞清楚思路，所以也就写不出文档。
从敏捷开发思想的角度去看待上述的一些问题：
对应 a1) 这就是敏捷开发反对瀑布模型的原因之一吧。
对应a2) 首先寄望于通过过程控制来达到开发人员可替换性目的这个想法，是有争议的 ，另外，极限编程中使用“代码集成所有权属于团队”的实践方法来保证团队内部的知识共享，从而减少人员流动对团队带来的风险。
对应a3) 敏捷开发的建议是只写有用的文档，例如编写整个系统的HLD或架构文档是值得的，因为整个团队的成员以及新人都要阅读它来了解整个系统的架构和设计，而某 个模块的DD文档，它的读者只是负责该模块的程序员，敏捷开发的建议是面对面进行交流来传达设计比较来得快捷，不编写过于详细的DD文档的原因是它太容易 与代码脱节了，另外，面对面交流，并不是资深人员传达设计给资浅人员，而是让资浅人员参与到设计中来，是以平等的方式与资深人员一起讨论和确定最终的设 计。可是文档毕竟比起代码易于阅读，总得要有个载体描述模块的DD设计啊，一般来说是推荐“Self-Documenting ”的形式来代替DD文档。
对 应a4) 轻量级的文档不代表不编写文档，所以这一点与知识库的建设不冲突。
对应b1) 尽量使用“Self-Documenting”的形式，即将文档以注释的形式插入到代码中，来解决文档与代码的同步问题，需要文档时，再用工具从代码中提 取出文档，例如Java中的JavaDoc工具，而Qt的API文档也是这么干的，Qt的文档是用doxygen来生成的。
对应b2) 这就是轻量级文档的原则所要解决的问题，除了避免编写无用的文档外，如何避免长篇大论的文档也是要解决的问题，我从UP开发方法的产出物（制品）中了解 到，UP开发方法使用的“用例驱动”方法将需求分析文档以“用例(Use Case) ”的形式来编写，减少了出现长篇大论的可能性。
剩下的 b3,b4,b5是开发人员自身的原因。
最好做个总结，文档是好东西，但它的弊端就是要花时间（包括写作和维护的时间），如果项目时间都比较紧，如何把握文档的量和细致程度，确实是值得思考和权衡的问题。
文档是个好东西，这是不可否认的，但是太依赖文档也有弊端，下面我从不同的度来分析一下文档的利与弊，然后思考在敏捷开发时，文档又是如何进行的。
从 公司的角度来看，编写文档有如下好处：
a1) 公司使用的是瀑布生命周期（或序列式开发，传统开发），所以必然的，在某一个阶段，需要编写大量的文档作为进入下一阶段的输入。
a2）过程改进的 需要，认为只要过程控制得足够细，例如只要文档编写得足够详细，那么人员是可以被替换的，也就是说，有了文档，人员的流动不会给项目带来大的风险。
a3） 受到其它行业的启示，例如建筑行业，图纸制定好并确否没有问题后，施工队才能准确无误地施工，所以要求在编码之前先编写HD、DD文档,除了方便交叉 REVIEW，同时，文档用于指导资浅工程师的编码工作，文档只有编写的足够详细(DD最好给出伪代码)，工程师才不至于走偏。
a4) 企业知识库的建设需要，没有文档，技术就没有得到积累。
从工程师的角度来看，为什么工程师有时不愿意写文档呢？
b1） 代码与文档的同步问题，很多设计文档在写完后就被代码远远地抛在后面了，开发人员只有二个选择，要不更新文档，要不任由文档逐渐地开始撒谎，如果选择维护 文档与代码同步，那么就会耗费大量的时间和精力在文档更新上面，而维护这份文档目的只是为了将来有可能有人需要阅读---也有可能无人问津。
b2） 任务的工时安排得很紧，但编写文档又导致进度太慢。
b3）认为文档太枯燥，不比编写代码有成就感。
b4）没自信，怕文档写不好会误导别 人。
b5）本身没有搞清楚思路，所以也就写不出文档。
从敏捷开发思想的角度去看待上述的一些问题：
对应 a1) 这就是敏捷开发反对瀑布模型的原因之一吧。
对应a2) 首先寄望于通过过程控制来达到开发人员可替换性目的这个想法，是有争议的 ，另外，极限编程中使用“代码集成所有权属于团队”的实践方法来保证团队内部的知识共享，从而减少人员流动对团队带来的风险。
对应a3) 敏捷开发的建议是只写有用的文档，例如编写整个系统的HLD或架构文档是值得的，因为整个团队的成员以及新人都要阅读它来了解整个系统的架构和设计，而某 个模块的DD文档，它的读者只是负责该模块的程序员，敏捷开发的建议是面对面进行交流来传达设计比较来得快捷，不编写过于详细的DD文档的原因是它太容易 与代码脱节了，另外，面对面交流，并不是资深人员传达设计给资浅人员，而是让资浅人员参与到设计中来，是以平等的方式与资深人员一起讨论和确定最终的设 计。可是文档毕竟比起代码易于阅读，总得要有个载体描述模块的DD设计啊，一般来说是推荐“Self-Documenting ”的形式来代替DD文档。
对 应a4) 轻量级的文档不代表不编写文档，所以这一点与知识库的建设不冲突。
对应b1) 尽量使用“Self-Documenting”的形式，即将文档以注释的形式插入到代码中，来解决文档与代码的同步问题，需要文档时，再用工具从代码中提 取出文档，例如Java中的JavaDoc工具，而Qt的API文档也是这么干的，Qt的文档是用doxygen来生成的。
对应b2) 这就是轻量级文档的原则所要解决的问题，除了避免编写无用的文档外，如何避免长篇大论的文档也是要解决的问题，我从UP开发方法的产出物（制品）中了解 到，UP开发方法使用的“用例驱动”方法将需求分析文档以“用例(Use Case) ”的形式来编写，减少了出现长篇大论的可能性。
剩下的 b3,b4,b5是开发人员自身的原因。
最好做个总结，文档是好东西，但它的弊端就是要花时间（包括写作和维护的时间），如果项目时间都比较紧，如何把握文档的量和细致程度，确实是值得思考和权衡的问题。