1 引言

大多数工程师在撰写需求文档的时候，主要考虑的是如何把逻辑讲清楚。这实际上是从自身出发的一种思维模式。所谓的讲清楚，是自己认为讲清楚了，因为自己本身已经有一定的认识，所以只要写下来的是对的，那都属于讲清楚了的范畴。但自己认为得讲清楚未必等于读者的讲清楚了，读者由于原来对该事物没有认识，或者虽有认识但有些偏差，因而，当读者通过文档收获的东西不完全等于写者想表达的所有内容时，就不能定义为讲清楚了。笔者建议，在撰写需求文档时，要用目标读者的角度去衡量怎样把事情交代清楚，怎样能够让目标读者方便阅读、方便理解。做到心中有读者，就能使得软件项目需求文档的质量不断有提高。

2 需求文档的涵盖范围

一般情况下，需求文档用需求模型和以用例为主体的文档相结合来表现。模型可以给读者以清晰、明确地主观印象。但因为其抽象性，不能把所有信息表达出来，更需要以文字解说的方式来补充。当一堆信息丰富的文字不分轻重缓急放在一起呈现给读者的时候，读者体会到的是杂乱，需要花很多心思去理清关系。用例在这时就应运而生，它能够帮助编写者很好地组织信息，也可能帮助阅读者快速找到需要的信息。

用例是需求，如果编写恰当，用例可以准确地对系统必须要做什么进行详细地描述。但另一方面，用例不是所有的需求，用例部详细地描述外部接口、数据格式、业务规则和复杂的公式。用例只是需要收集的所有需求中的一部分，虽然这一部分非常重要，但毕竟仅仅是一部分。业务规则、词汇表、性能目标、过程需求和许多其他方面的东西都不属于行为需求之列，因此不属于用例的范畴[1]。本文的需求文档是一个泛指，泛指所有和需求有关的文档，包括用例、业务规则、词汇表等等。

3 需求文档的两难境地

笔者在一家公司的软件部门工作7年有余，参加过5个以上不同的软件项目组，更观察了超过10个以上公司内外软件团队的工作。目前软件团队中需求文档的读者主要是用户、客户;系统分析员、需求分析员;软件开发者、程序员;测试员;项目管理者等。方方面面的人员对于需求文档的不同要求，加上需求工程师们对自己撰写的文档的一些认识和要求造成了需求文档的一些两难境地，通过一些现象表现出来。

• 现象一：用户代表们看完所有的厚厚一叠需求文档(主要是用例)后，觉得很茫然，好像文档所叙述的内容都没有问题，但对根据文档开发出来的软件是否是自己需要的并没有把握。
• 现象二：开发工程师和质量工程师们总是反映需求文档不够细致，不能体现到每个按钮、每个字段的要求。对开发和测试工程师们来说这些信息确实属于需求的一部分，而对于需求工程师们来说，这样的文档撰写、维护所耗费的精力实在是无可估量的。在一些没有专职的系统设计师的团队中，需求工程师要拿捏尺度，在需求文档和设计文档中寻找平衡点，也不是一件容易的事。
• 现象三：在开发团队中做熟的一些工程师们，希望每个迭代的文档更有针对性。如果每个迭代的需求文档都是在之前的需求文档上的叠加，那么他们往往要花费很多时间和精力去把那些修改之处找出来。然而，当需求工程师们，顺应大家的要求，按迭代周期撰写需求文档时，新近加入的工程师们又抱怨连连：他们没有办法，看到系统到当下最正确且及时的情况以文档来反映，当他们从0.1，0.2版本的文档阅读到0.5，1.0时，赫然发现之前所阅读并记忆的很多东西其实已经完全被摒弃或者有了天翻地覆的变化。当然，也有可能当他们读到1.0版本时，已经不记得0.2版本写了什么了。
• 现象四：需求工程师们把需求文档看成是一个累赘，对他们来说分析清楚需求，是一件很有挑战的工作。然而，撰写需求文档，只是一个很枯燥的工作，看上去全然没有创造性，反而吃力不讨好——没有最好的文档，总有人有不满意见。在撰写新文档上，需求工程师们可能受到流程控制、实际需要而忙碌工作于文档上，但对于一些需求变更，或者对于需求文档中二义性词句的修改，就显得不那么按部就班。由于工业化的软件开发有很多进度的要求，造成文档评审的效果和结果都有些折扣，如此一来，需求文档更成为一种鸡肋，食之无味弃之可惜。

其实，对于需求文档，方方面面的意见实在太多太杂，举不胜数。然而，需求工程师们就真的在需求文档行这道坎前束手无策，坐以待毙么?答案当然是否定的。把需求文档的撰写看作是需求工作中的重要一环，把需求文档的质量看作是自身业务水平的一个体现，需求文档一定能有起到其在软件开发中的应有作用。

4 高质量需求文档的衡量标准

需求是一种知识，知识在被转播的过程中需要一种用载体来呈现，需求文档正是这样一种载体。如果需求本身在获取的过程中已经出现质量问题，那么需求文档质量再高也只能反映有缺陷的需求;反之，如果编撰需求文档的能力非常低下，那么高质量的需求在别人眼中就成为残缺不齐的需求。因此需求文档的质量要求和需求本身的质量要求实际上是一致的。两者密不可分。

对于需求和需求文档，目前普遍的认识是要具有以下特性，或称之为高下的衡量标准[2]。

1) 完整性：不能遗漏任何必要的需求信息，需求本身是要完整的，而需求文档也要完整地表述需求。

2) 一致性：需求之间要不相矛盾，在文档的字里行间也要保持一致。

3) 可修改性：需求会因为各种原因而发生变化，这是无可奈何的现实，需求文档总是体现需求，因此需求文档必须是可以被修改的。

4) 可跟踪性：应能在每项软件需求与它的根源和设计元素、源代码、测试用例之间建立起链接链，

5) 作为文档，可阅读性、可维护性、无二义性也都很重要。

6) 可阅读性：一般说来，第一眼看去版面规整、长度适当的文档是读者愿意阅读的。再看内容条理清楚、层次分明、能容易抓住重点的文档是读者在初读之后还愿意继续往下读的关键。

7) 可维护性：相同的内容如果无数次的出现并散落在文档各处无疑会给文档的长期更新带来隐患，可维护性反映在维护文档的人能够很容易的知道应该更新文档的哪些地方并且如何根据实际需要去更新。

8) 无二义性：文字的魅力在于丰富多样，而文字的挑战同样在这里，如何让读的人接收到写的人想要交代的信息，不多不少刚刚好，是一个很大的难题。

5 “想着读者”撰写需求文档的建议

建议一：每个文档或每段文字都要有明确的目标读者

为了减少维护文档的工作量，有些需求工程师喜欢用一个文档记录所有需求相关的信息。这当然不是不可以，但上文提到，需求文档的读者其实很多，用户、客户、系统分析员、需求工程师、开发工程师、质量工程师、项目经理等[3]。事实上，每个角色看文档的目的是不一样的，因此他们各自对文档的要求也是不一样的。从“为读者着想”的指导思想出发，高质量的需求文档，需要让读者一眼就能明白哪些是他关心的内容，他需要详细阅读，哪些是写给其他角色看的，他可以跳过不看，而不是等他读完了才发现这些信息和他无关。也就是说，即使只有一个需求文档，在文档中间也应该很用明确的标识来标记目标读者是谁。

当然，如果有些目标读者关心的内容有很大的不同，那么完全没有必要硬把所有内容放在一个文档里。因为那样会造成文档的冗长，极其容易让读者没有耐心去看。

建议二：利用模板，但不要被模板束缚

无论是RUP，IEEE还是Vorath，都提供了软件开发文档的模板，其中就包括需求相关的文档模板。模板是可以也应该根据项目和企业的实际情况进行裁减的，这是业界普遍认同的。但是随意翻阅一些软件项目的需求文档，尤其是通过了CMM/CMMI Level 3或更高级评定的软件项目，不难发现，文档中很多方面的内容流于形式。例如用例目的(Objective)大多都是“通过这个用例用户可以****”，****就是用例名或其近义词，又如，在系统响应速度的要求中，大多数都是“3秒内”或“平均3秒，最坏情况5秒”。这样的需求文档实际上是没有质量的。二出现这种情况的主要原因就是需求工程师觉得没什么可写，但又必须填一些内容。

事实上，在撰写需求文档时，发现任何一个段落(Section)的内容经常不知道怎么填，而随手写一句话或几个词的时候，就应该把问题拿出来分析。探讨一下这个段落是不是真的有用，那个角色会关心这个段落，是不是可以不要这个段落，如果还是有保留意义的话，那应该怎样写才能起到该段落的作用。如讨论对系统响应速度的要求，需求工程师们就会发现，在商业系统中，数据量对系统的响应速度影响很大，因此，宽泛的说3秒完成一个动作是不合适的。相反，需求工程师应该详细给出诸如“70%的集装箱装载的货物在100种以内，要求3秒内用户可以在系统界面上看到集装箱内的全部货物信息，100-200种货物的集装箱信息要求在5秒以内显示，若货物条目超过200条的情况系统可以不考虑。”

建议三：多些业务信息、假设(Assumption)

描述事物的方法无外乎两种方法，一种是描述对的情况，把对的信息一条条叠加，就能看到对的事物的全貌。第二种是描述排外情况，把世界比作一个大空间，那些排除出去的以外就是人们需要的事物了。大部分情况下，需求文档都用第一种方法来描述需求，即需求是什么。然而，世界太大，每一件事物可以从许许多多不同的角度来描述。而需求文档是有限的，人的思维也有一些定式。因而需求文档一定做不到完美——无一遗漏、一网打尽。这时候，建议用两种方法结合的方式，来对需求进行描述，就会更好。

假设信息实际上有很重要的作用。根据投资回报率理论，系统目标解决80%的业务，而不是100%，因此遇到一些特殊情况，很有可能在需求讨论的时候已经有决策，即不需要系统处理这些情况。其实这些排外情况也是需求的一部分。应该要在需求文档中得到体现。笔者接触的很多项目都忽视了这点，因而造成日后在系统运行过程中用户和开发团队产生分歧，用户觉得是系统缺陷，而开发团队觉得需求就是如此，但苦于没有文档作证。

前文的例子中，“70%的集装箱装载的货物在100种以内”就是对“对的”需求的描述，而“若货物条目超过200条的情况系统可以不考虑”就是一种排外情况。两者结合起来，才能让开发工程师和质量工程师知道应该怎么进行。

多描述业务还有几个好处[4]，其一，业务其实很少改变或者说改变得很慢，但系统是很容易就需要改变的，多描述业务实际上可以降低文档的维护工作量。其二，尤其对于商业应用系统，如果能够尽可能的让开发工程师和质量工程师明白业务是怎么回事，那么开发工程师可以从需求中看到业务，在进行设计、编码的时候，为业务长远的发展预留空间，而质量工程师可以更多地设计符合80%业务的测试用例，而不仅仅按照测试理论来设计测试用例，那么这样的测试能够更有针对性和效率。

建议四：规范用词，提供适当的阅读指南

大部分关于用例模板、需求规约模板中都有“词汇表”这个部分，的确这是一个规范用词的做法，词汇表实际上也是对一些专有名词进行注解，以方便读者理解。然而，用词的规范，应该不仅仅只是专用名词、术语，更可以推广到动词和句式。

需求文档作为技术文档的一种，和普通文艺作品截然不同。文艺作品讲究重复强调主题，但又需要用很多不同的近义词来凸显主题。而作为技术文档，同义词只会引起一些敏感的开发、测试人员的疑惑。例如“编辑Edit”、“更改Modify”、“修改Amend”、“维护Maintain”究竟在文档中表明一个意思还是各有不同，的确是一个值得揣摩的问题。需求撰写人的随意用词会给认真的读者带来很多遐想空间，这在文艺作品来说可能是一种效果，然而技术文档不需要。如果需求文档撰写人对这些近义词的用法能够有一个说明，并且在所有文档中保证用法一致，那么无疑会受到读者的好评。因为这样一致的做法可以确保无二义性的产生。

需求文档在句式上也可以用一些方法来规整[5]。比如，表示用户想要开始进行某项操作时，不写成“用户进入**菜单”，而写成“用户想要进行**操作/工作”。那么，当一份文档里第三次出现这个句式时读者就能直奔主题，直接阅读中间是什么核心内容，而不再需要阅读前后的辅词。

其实，这样做同样能给需求文档撰写人带来好处也是很明显的。在撰写需求文档的时候，一个词可以表达一种确切的含义，甚至可以超出词语的本意，而不需要每次洋洋洒洒重复介绍;同样的句式可以把重点放在主题上，让工作更有效率，在以后的维护中，也可以用工具帮助查找同样的词或句式，保证没有遗漏。

建议五：善用各种工具进行版本管理

由于需求文档的可修改特性，文档的版本管理也是相当重要的。专门用于文档管理的工具有VSS，Sharepoint等，但是没有这些专业工具并不表示就不能进行文档的版本管理了。Microsoft Word加上合理创建文件夹结构就可以很好地解决文档版本管理的难题。

对于文档版本的管理，有两个主要目标，一是总能找到最近的一个版本，也就是最后更新的，这个文档能够给任何团队外的咨询者或者团队中的新成员以足够的信息，所谓最后更新，即能够在没有任何修改或情况说明的情况下，提供文档让需要者去阅读，而不会因为某些需要者提出要求才去修改更新文档。二是能够快速定位某年某月的某个版本究竟有哪些改动，改动之前是怎样的，改动之后又是怎样的。如果哪个版本恰巧和软件产品的一个发布版本吻合，那么开发工程师和质量工程师们实际上只要关注那些改动的部分就足够了。换言之，达到以上两个目标就很好地解决了现象三种的两难境地。

善加使用Microsoft Word中的Track功能是一个很好的建议。当决定文档需要保留一个版本的时候，就应该把当前的文档另存，并修改文件名，增加版本信息，例如“需求规约v2.3.doc”。 而主文件名保持没有版本信息的状况“需求规约.doc”。当开始新一个版本周期v2.4工作的时候，第一件要做的事情就是全部接受(Accept All changes in document)上一个版本所做的所有改动，然后再根据实际情况进行文档修改。如此一来，所有v2.4的更新都会被Word记住，以方便读者在需要的时候，通过(showing markup)或修改区域(Reviewing Pane)进行快速寻找定位。此外，不建议每个版本周期创建一个文件夹，存放该版本所有文档的做法。因为有些文档可能由于该版本没有被改写而不会出现在该文件夹中，造成被人忽视，或找不到的情况。建议文档可以在一个文件夹里全部找到最后更新版本，同样在这个文件夹下，可以找到被归档的以往的版本文件。

6 结束语

近年来，敏捷过程、敏捷文档是被广泛提及和研究的论题。然而，敏捷的提出并非打着“敏捷”的幌子逃避文档的编写、管理的问题[6]。笔者以为，敏捷，实际上指的是敏捷的撰写文档，还要加上敏捷地阅读文档。

关于如何提高需求文档的质量，其实还有很多小建议，例如从文档排版角度如何提升文档的可读性，从文档结构角度应该要提供一个文档指引，从文档管理角度如何使用文档之间的相互链接(文件夹有进行整理、移位的可能)等等。

真正做到心中有读者，在编撰文档的时候，应该总是考虑读者想看什么，怎样可以快速看文档，怎样可提高文档的有效利用率却又不过分地夸大一个文档的作用，诸如此类。能够用这种服务的心态去编写需求文档，一定能编撰出高质量的需求文档，为整个软件项目成功做好第一步。