Just enough（刚刚好）的软件开发文档什么样？

在今年与多个软件开发单位的交流中，补文档的问题多次提到，试图通过本文谈谈文档的价值，如何写刚刚好的文档。

软件开发所需要的文档在传统的瀑布型生命周期下典型的有：开发计划，需求规格说明书，设计书（有分成基本设计书、详细设计书；也有分成High Level Design、Low Level Design；或者概要设计、详细设计), 测试计划（测试用例），测试报告，结题报告。其中的需求规格说明书和设计书是过程中最重要的两份文档，往往多达数十页，甚至数百页。 后期，文档与实际软件的一致性问题是比较突出的，往往出现软件已经修改，而文档还没有修改，两者不一致。

敏捷开发针对这种情况提出了“可用的软件 重于 完备的文档”，提出文档要Just enough。

那么到底如何Just enoughJust enough的对比是什么呢/p>

大而化之，可以将文档的“Just enough”归纳到三种不同的极端需要：

1，通过文档，只要让明天加入这个团队的新人了解所要知道的内容就行了，不在文档中的内容，团队老成员会通过诸如结对、协作等等方式告诉新人；

2，通过文档，可以处理当前项目结束后的维护，或者是后续跟进项目。

管理层和敏捷团队自身可以考察团队的稳定性，项目所处阶段来判断需要什么样的文档。如果团队成员离职率高，文档需要就大，如果项目处于晚期阶段，那么要考虑项目结束后团队去向，如果团队会解散，那么文档需求显然，如果团队会留下，那么文档还是可以少些。因此这个问题是可以处理的。

3，客户需要的文档，这个没啥说的，客户付钱要文档，当然要写了。

从这3种情况来回看需求文档和设计文档，就会发现，“真的不用写这么多文档”。厚达100页的需求，让新人读一遍都是一件烦人的事，而且新人也未必理解。如果软件已经运行，界面做得友好，新人运行软件来理解需求，效果比读文字可要好的多，甚至给用户的使用说明书都可以写得简短些。

有一个常见的情况：就是补文档。这种情况是软件已经开发出来了，但由于规章制度等等原因的要求，要求补出文档。

我们可以反思这个问题：既然没有文档的情况下，软件都开发出来了，为什么还需要补文档是不是可以修改开发流程，取消原来的写文档环节/p>

如果原因是“所补的文档是用户使用手册，用户在使用中是需要的”，这个补的文档显然是有价值的。

如果原因是“所补的文档是需求规格说明书和设计书，没有这个，XXX部不让结题”，这个看起来就没有价值，从流程上取消文档环节也不妨碍软件开发。

如果原因是“合同规定了有这些文档，不写，拿不到尾款”，这个没啥说的，为了钱也要写，问题是下次合同时要么取消这个文档条款，要么按合同要求及时写文档。

如果原因是“所补的文档是需求说明，没有这个就没法对应测试用例，测试不能保证完整性”，软件已经开发出来了，已经可以运行了，也有使用说明，那么测试用例已经可以设计，测试已经可以开展了。测试用例没有必要一定对应需求的文字了。 运行的软件+使用说明 本身可以理解为需求的一种表达形式。

如果“我们后续修复缺陷，都是直接查代码，从来不看老需求和老设计”，那么文档的作用几乎没有了。

软件快速出来，反而符合敏捷12条原则中的第1条”我们重视通过尽早、连续的提供有价值的软件来满足顾客。”

因此补文档还是要看文档的价值所在，没有价值的文档是不值得补的。文档的价值主要分2类：1，满足客户需要；2，帮助后续维护。

从软件开发本身来说，文档大多是不值得补的。如果一个组织出现大量补文档的情况，那肯定意味着这个组织的软件开发流程可以调整了，简单可行的思路是：如果文档是有价值的，那么应当及时书写；如果文档是没有价值的，取消文档环节。

作者：张克强

blog:   http://blog.csdn.net/zhangmike     允许全文转载。