为什么要写文档？

很多人一谈起 RUP 或者 CMMI 流程改进的第一反应就是在项目过程中会多出很多文档，那么多的文档岂不是要占用我们很多的时间？这种看待文档的心态一定会影响到流程改进的效果，我们从事的是高科技的创造性工作，为了满足公司规定而写的文档跟自己心甘情愿要写的内容肯定有很大的差别 ，应付了事的表面文章必然是满足不了这样标准化文档原定的目标。我就看到过有开发人员先编码再写设计文档的，基本上就是代码的自然语言翻译，典型的逆向工程。

关键在于怎么样看待文档在软件开发过程中的作用，如果把它看成是开发过程中额外的负担，你就会为了写文档而写文档；如果把它看成是开发过程中自然的一部分，你就会乐于接受它，因为文档就是最终交付产品的一部分。举一个例子，下面的乘法算式中我做了一个简单的类比，原始的运算需求比作是需求，中间的运算步聚比作是设计文档，最终的运算结果就是我们要的目标代码。

如果你能够把设计文档看作是从需求到目标代码的一个中间步骤，你就不再会认为它是一个多余的东西了，相信你也会很乐意地去做它。那我们日常开发中往往又不需要设计文档，大部分情况下的原因就是我们所要开发的软件太过简单了，简单到我们在脑子里也可以完全想清楚；或者是更多的时候，我们只是在原有代码的基础上做一些修补工作，而不需要在白纸上从需求直接跳跃到最终结果。就象这里所举的例子，完全可以靠心算得出结果，但是如果我要让你来手工计算12345*67890的话，相信你一定会利用一个乘法算式来得到结果的。相对于目标代码，设计就是一个介于需求和代码之间的中间产物，它要比需求更接近代码，但又要比代码简单一些。

当然文档不仅只是一个中间过程，文档在开发过程中最主要的职能是“沟通”。 软件开发中最困难的工作是哪一部分呢？我听到最多的答案是“需求”，需求的混乱在于你和客户以及其他涉众之间的沟通不畅和效率低下。对于一个开发团队，最大的挑战来自于团队成员以及涉众之间的沟通，文档就是一种沟通的基本工具。小型的项目，涉及的人员较少，我们可以选择一个轻量级的流程（需要产生的文档也较少）；大型的项目，涉及的人员较多，我们可以选择一个重量级的流程（需要产生更多的文档来帮助团队成员之间的交流沟通）。

文档的沟通功能主要作用在横向和纵向两个维度，横向的一方面文档可以使项目成员了解其他相关人员的工作成果，如设计人员需要根据分析人员的需求文档来设计系统架构，所有的项目成员都需要根据项目经理所制定的项目计划来了解各自的开发任务。纵向的一方面文档也是日后系统进行维护扩展的依据，开发人员需要阅读项目以前的设计文档来理解系统结构，然后才能在此基础上对系统进行修改。

几个人的项目，每天碰一次面讨论一下，就可以完成沟通的目的，一个会议记要就可以记录下所有的问题和行动计划， 敏捷过程的代表 XP(eXtreme Programming)  就比较适用于这种小型的项目。对于几十人的项目，这样的沟通方式就不适合了，我们需要一些正式的文档来帮助团队的沟通，如：项目开发计划、软件需求、设计文档、测试计划等等，这些都是为了帮助横向的沟通。在纵向的沟通上，我们更需要一些必要的文档来帮助传递项目的关键信息给将来版本的开发人员。

既然文档的主要职能在于促进团队沟通，我们就有必要制定一些标准来保证沟通的效果。对于同一企业内部的不同项目，我们当然希望每一个项目都采用同样的文档体系，甚至是文档的格式，这样我们从一个项目切换到另一个项目时，我们都能够很顺畅地阅读理解每一个文档。RUP 中就提供了一整套的软件项目过程文档模板。

除了沟通之外，文档也是一种帮助我们整理自己思路的工具。很多想法一旦要落笔记录下来，我们就会更加仔细地考虑其完善性（举个例子，文档的这个作用本身就是在写这篇文章的过程中才想起来并补充进来的）；很多在脑海中似是而非的内容也会在文档化的过程被加以细化和规范化。回想一下你从客户那里收集需求的过程，每一个业务人员都只跟你描述他所知道的那一部分业务流程和需求，你需要把每个人的描述都记录下来，然后再综合整理成一个完整的业务流程和需求描述。有些业务处理规则在日常工作并未规范化，可能不同业务人员的理解略有差异，在把这些需求文字化的过程中，我们就会规范这些业务规则，以保证所有业务人员的认同。

文档并不应被误解成一种额外的负担，如果有这样一种感觉，只有两种可能：或者是你没有理解这个文档在整个项目中所起的作用，或者是公司所规定的文档在这个项目中根本上就是不必要的。