在今年与多个软件开发单位的交流中，补文档的问题多次提到，试图通过本文谈谈文档的价值，如何写刚刚好的文档。
软件开发所需要的文档在传统的瀑布型生命周期下典型的有：开发计划，需求规格说明书，设计书（有分成基本设计书、详细设计书；也有分成High Level Design、Low Level Design；或者概要设计、详细设计), 测试计划（测试用例），测试报告，结题报告。其中的需求规格说明书和设计书是过程中最重要的两份文档，往往多达数十页，甚至数百页。 后期，文档与实际软件的一致性问题是比较突出的，往往出现软件已经修改，而文档还没有修改，两者不一致。
敏捷开发针对这种情况提出了“可用的软件 重于 完备的文档”，提出文档要Just enough。
那么到底如何Just enough？ Just enough的对比是什么呢？
大而化之，可以将文档的“Just enough”归纳到三种不同的极端需要：
1，通过文档，只要让明天加入这个团队的新人了解所要知道的内容就行了，不在文档中的内容，团队老成员会通过诸如结对、协作等等方式告诉新人；
2，通过文档，可以处理当前项目结束后的维护，或者是后续跟进项目。
管理层和敏捷团队自身可以考察团队的稳定性，项目所处阶段来判断需要什么样的文档。如果团队成员离职率高，文档需要就大，如果项目处于晚期阶段，那么要考虑项目结束后团队去向，如果团队会解散，那么文档需求显然，如果团队会留下，那么文档还是可以少些。因此这个问题是可以处理的。
3，客户需要的文档，这个没啥说的，客户付钱要文档，当然要写了。
从这3种情况来回看需求文档和设计文档，就会发现，“真的不用写这么多文档”。厚达100页的需求，让新人读一遍都是一件烦人的事，而且新人也未必理解。如果软件已经运行，界面做得友好，新人运行软件来理解需求，效果比读文字可要好的多，甚至给用户的使用说明书都可以写得简短些。
有一个常见的情况：就是补文档。这种情况是软件已经开发出来了，但由于规章制度等等原因的要求，要求补出文档。
我们可以反思这个问题：既然没有文档的情况下，软件都开发出来了，为什么还需要补文档？ 是不是可以修改开发流程，取消原来的写文档环节？
如果原因是“所补的文档是用户使用手册，用户在使用中是需要的”，这个补的文档显然是有价值的。
如果原因是“所补的文档是需求规格说明书和设计书，没有这个，XXX部不让结题”，这个看起来就没有价值，从流程上取消文档环节也不妨碍软件开发。
如果原因是“合同规定了有这些文档，不写，拿不到尾款”，这个没啥说的，为了钱也要写，问题是下次合同时要么取消这个文档条款，要么按合同要求及时写文档。
如果原因是“所补的文档是需求说明，没有这个就没法对应测试用例，测试不能保证完整性”，软件已经开发出来了，已经可以运行了，也有使用说明，那么测试用例已经可以设计，测试已经可以开展了。测试用例没有必要一定对应需求的文字了。 运行的软件+使用说明 本身可以理解为需求的一种表达形式。
如果“我们后续修复缺陷，都是直接查代码，从来不看老需求和老设计”，那么文档的作用几乎没有了。
软件快速出来，反而符合敏捷12条原则中的第1条”我们重视通过尽早、连续的提供有价值的软件来满足顾客。”
因此补文档还是要看文档的价值所在，没有价值的文档是不值得补的。文档的价值主要分2类：1，满足客户需要；2，帮助后续维护。
从软件开发本身来说，文档大多是不值得补的。如果一个组织出现大量补文档的情况，那肯定意味着这个组织的软件开发流程可以调整了，简单可行的思路是：如果文档是有价值的，那么应当及时书写；如果文档是没有价值的，取消文档环节。
关于作者
张克强
系统分析师，Certified Scrum Master，2002年毕业于清华大学。现在是宝信软件过程改进首席咨询师，负责领导咨询团队把业界最佳实践和自身有效实践应用到宝信的各个研发单元中，并组织和协调各单元的过程改进评估和审核。在软件工程方面拥有8年经验，他的经历主要在组织的过程改进、质量保证和测试方面，帮助组织按CMM/CMMI模型进行改进，并通过了CMM4、CMM5、CMMI5的评估，从2007年起宝信软件引入了以Scrum为主体的敏捷开发方法，在软件质量和开发效率方面都获得了明显的改善。他也曾担任水木软件工程版版主。
他的博客地址是：http://hi.baidu.com/hespr
