《产品研发过程实践》（13）需求文档的撰写

作者:asky 日期:2007-04-29

字体大小: 小中大

在这里，之所以把这章单独拉出来，是因为需求文档，一直是我们的一个大问题。过于详细的，而且缺乏分层和索引的文档，引起的是更新不及时，而且耗费大量成本。成本一点我们多少还能够接受，但是千万不要低估他的成本，认为这些文档可以随手就改过来，正式自己操作的人，就会明白，这远远不是随手改过来的问题，当然，一个文档如果结构相对合理，能够组成立体的层面，那么修改还相对简单一些，如果一锤子到底，全部是扁平的User Case的模式，那么很不幸，如果某一个地方发生一点全局性的变动（比如增加了一个在我们系统中，用户必须首先登录，不然不能使用），那么分配到每个User Case中，这将是非常庞大的工作量。对此千万要小心，文档不仅仅是写出来就完事的，将来还是要维护和更新的。另外一个极限是，几乎没有需求文档，几乎所有的需求都是简简单单一句话，比如“用户的数据需要定期备份”这一点，就存在大量的分支，是系统自动备份？还是定期提示用户自己备份？最近一个备份会覆盖前面一个备份结果吗？这些备份数据，会自动清理吗？备份的数据，用户能够进行什么操作？等等，如果这些问题都是一无所知，就直接进行开发，无异于把自己的命运完全寄托在幸运上（而且是非凡的幸运），因为这意味着，所有这些疑问，如果被提出来，还算好；不然，这些将完全依赖于大家自己的设想，而要保证大家的设想是完整的的概念集中一部分，那么这多少可以称之为奢望了。

针对上面这两种情况，都不是我们想要的，在其中，我们希望有个平衡点。

在这里，我首先要说的一点，是我对于文档的看法；无论过程多么重要，但是过程的保证是为了目标的保证，如果一件事情对于客户的直接价值不大，我们就需要极其小心地对待这件事情，因为我们要记住的是目标。那么做为重要的沟通方式和知识固化的一种做法的文档，我们应该如何看待呢？

首先需要明确的一点是：项目管理不是文案管理，这一点请千万记住，不要看着一堆堆的文档，就认为自己是在管理了，如果这就叫管理，那么不如说你是一个文档保管员更恰当一些。什么文档，是我需要的文档呢？我认为应该具备三个条件：

1.          这个文档必须是团队能够进行更新和维护的，如果一个团队根本没有精力对N份文档加以维护和更新，为了保险起见，你还不如不要这份文档，因为你根本无从知道这些文档中，哪些是正确的，哪些是错误的。举一个例子，我们大家都知道，在开发过程中，随着版本提交的，不仅仅包括源代码，还将包括数据库表的初始化代码等环境建设的东西。如果你面对的是一个根本没有人能够保证的数据库建表和初始化脚本，你的第一反应一定是：算了，我还是直接从开发数据库做数据库反向工程好了。的确是这样的。但是，我们能够做需求、设计文档的完整的反向工程吗？很明显，这是不可能的。这种似是而非的文档，造成的危害会大于没有这些文档。没有文档，让人只能花费极大的精力，从中重新整理出思路来，但是如果错误的文档（特别是不知道哪里是错误，而且前后相互间是矛盾的文档），给人带来的就是不断的挫折感。如果你的团队比较成熟，能够很好地认识到某些文档是至关重要的，必须严格维护的；那么就推行下去，不然，还是分步骤来走好了。

2.          这个文档必须是能够为下一个阶段提供输入的。文档不仅仅用来评审，而且还用来对下一个阶段的工作提供指导，如果某一个文档不能为下一个阶段提供输入的，除非有其他原因，不然，不如不要，因为无法用下一个阶段工作来进行检验，那么Final Check的人员即使再认真，也很难保证这个文档的确是没有问题的。举一个例子来说，很多团队，在项目结束的时候，来补充Detail的文档，这将花费很多的时间，而且这部分工作的价值何在呢？为将来做程序的人提供一种快速浏览的方法？我不这么认为，因为为写文档而写的文档，一般来说是达不到这种效果的。当然，如果你面临的是下一个迭代版本的开发，那么提前抽出一段时间，对这些设计文档加以完善和补充，我认为还是值得的，不然你下一个版本的设计都不知道应该在哪份文档上进行补充。

3.          这个文档必须是标志着一个阶段成果的，而不是那种记录过程的。举一个例子来说，值得保留的设计文档，应该是那种设计结论性的文档，而不是事无巨细，包括设计过程中的各种思路都写入进去的（当然，全局性的考虑和总体设计思路，还是需要的）。因为记录过程的文档，一般而言是基于这样两点的假设，来做的：首先我们认为，这样的文档将为将来的阅读的人提供更多的信息，但是，就我在项目中的经验来看，我们面对文档的时候，最大的问题，不是企图从文档中读到最多的信息，而是首先要的是正确的全局性的信息；其次，我们认为，记录过程的文档，将使得我们能够看见整个事情的发展顺序，从而对系统更加了解，这一点从一个方面来说是正确的，比如在项目过程中，但是，这将导致非常难以阅读，非常难以维护，也许你觉得这样很清楚，但是这往往是因为你在维护这个文档，让一个第一次接触这个系统人来看这个文档，就是一场灾难了。而且，更为麻烦的是，这种文档，将慢慢变得象草稿纸一样的东西，似乎上面什么都有，但是什么都看不清楚，就不值得了。

我自己的做法是这样的，首先文档是需要有层次结构的，而且不是一份文档组成的，比如，我会在需求文档的开始，描述这个软件的基本软件List表格，这些表述了客户提出的最基本的一些需求；然后，我会分开进行描述，比如对于用户某一个业务流程，我会使用User Case来加以描述，但是在描述这些User Case以前，我会描述一些整体的结构，来表述这个软件的一些基本框架，比如我会使用层次结构图，来表述用户的菜单结构是什么，我会使用一些框架图来表述用户各个不同层次的人，在描述某些软件的模块的需求，提炼出来一些全局化的东西，分离出来（比如用表格形式，来说明某几个模块，能够被某几种角色所访问等等），使得User Case仅仅描述一些他本身的东西。这样的文档，相对的来说，比较容易修改和表述。

再其次，我会把类似UI原型也做为需求文档中的一部分，虽然从严格意义上，这些应该是设计，而不是需求的一部分；但是由于我们需要记住的一点是，用户往往也是在不断学习中，他们也在随着项目组一起对系统增加了解，所以，他们也会不断提出需求，而这些需求往往是从他们最熟悉的部分开始的，比如他们直接所触摸到的UI部分开始的。而且，我将在后面不断使用这些原型和客户进行交流，同时，他也是变化可能性最大和最不稳定的部分，所以，我个人倾向于把这部分内容做为需求的一部分来保留；另外一个原因是，UI原型可以说是一个最好的需求说明文档（当然这指的是业务系统，对于协议机等等处理，还是老老实实地做User Case，更能说明问题），一幅图所携带的信息量有时候比1000句话更到位和更有效。

在提到需求的时候，我也想说明自己的一个对于需求的观点，我们常常讨论关于项目中最困难的一个点，我想，很多人都会提到：变化！对于变化我们的态度是什么呢？这一点，在2002年，联想政府事业部的一个总监，和我提及的一个观点，令我有一些触动：变化是我们价值的体现，如果没有变化，我们这些人就没有存在的必要了。所以，首先，我们必须感激变化，再次，我们需要应对变化，为什么瀑布模型或者其他任何以冻结某一个阶段工作为前提，然后展开下一个阶段工作为特点的过程，在实际的使用过程中，总是让我们觉得很难受，其实很简单的一点就是：变化成本太高，以至于我们首先所做的就是抵制变化，但是，我们常常发现，变化是难以抵制的。这一点不管国内还是国外都是如此，我们都是处于这样的环境中。那么如何使得变化的成本相对低廉一些？我们可以采用技术的手段来使得变化更为容易，比如面向对象的设计，比如一些经典的设计模型等等，都是如此。其次，我们采用一些折衷的流程，来快速响应变化，比如敏捷宣言所宣称的那样（有一次，在Javaeyes的网站上，看见Ozzzzzz老兄，写的一份了解客户需求，然后如何撰写客户接受的需求文档的文章，让我感触很深刻，他建议采用一种简单，明了的描述方式来描述原始需求，然后就这些List需要客户签字，后面的很多工作，依赖于和客户之间的直接沟通来不断完善。这一点，至少我和以前作实际面对客户的项目来说，是一种比较实际的做法）。当然，我并不是说，采用了上述的手段，就一定可以解决快速变化问题，事实上，这两者，只是开始面向客户，而不是面向自身，承认变化的必然性，所以，一味把用户的做法纳入我们自己的流程来进行约束和规范，还不如，我们从一开始就考虑变化这个因素。这也就是说，能够面对事实的流程，或者做法，更让我们能够接受。而一层不变的做法，也许适合于一些环境（比如严格定义了需求和设计框架，剩下的大部分工作是填充代码工作的日本软件外包环境等等），但是不太适合我们更实际碰到的环境。这一点，还是需要我们所有人记住的。

需求变化之所以是不可避免的，我理解的原因有以下几个方面：首先，我们面临的世界本身在越来越快地变化中，特别是商业社会中，发生的变化越来越快，也越来越大，那么在做为辅助客户进行商业活动的IT系统来说，没有理由不发生任何变化（这不切实际，不是吗？）；其次，由于软件产品的特殊性（他往往和人发生非常密切的接触，并且很多软件是在不断地和人头脑中的知识发生碰撞，来产生价值的），所以，客户也和我们一样，也在不断的成长中，在我们学习业务的同时，客户也在学习着IT方面的知识，双方的不断交流，使得客户的想法自然而然发生变化，这一点是业务系统的研发过程中，是十分明显和重要的一个过程。那么OK，我们就是需要欢迎变化（你不欢迎恐怕是不成的了！），我们就是要考虑快速变化（考虑考虑你在焦油坑中的下场也许会让你更有感触的）。

其实，需求这一块，我写得还是大大不够，比如我没有针对很多面向客户的需求获取和需求分析过程，我没有展开一些常用的需求分析方式，甚至没有提到和客户进行沟通和交流的一些行为技巧，但是，我没有展开这一块的原因，是因为以下两个原因，并且希望我将来能够独立写一些东西来表述：

1、在这一点上，我必须承认，我的经验还不足以支撑起来整个体系（我只能零零散散地讲一些技巧或者知识，但是缺乏一条足够健壮的思路来进行贯穿，能够完整地表达出自己的想法），抄写很多人卓越的文档，实在让我觉得有点糊弄的感觉了，甚至有种偷盗的感觉；

2、需求过程实在是我们最重要的一环，如果这一环做得不好，那么后续的很多工作就全白费了，而且他又是最难以用一种规定的东西来进行约束的过程，所以，还是等待我自己有空再整理整理思路，然后写下来吧。其中也许会包括需求的表述、需求的获取、和客户之间的沟通等等。