论软件项目需求文档的撰写.docVIP

论软件项目需求文档的撰写 ? ? 1 引言 大多数工程师在撰写需求文档的时候，主要考虑的是如何把逻辑讲清楚。这实际上是从自身出发的一种思维模式。所谓的讲清楚，是自己认为讲清楚了，因为自己本身已经有一定的认识，所以只要写下来的是对的，那都属于讲清楚了的范畴。但自己认为得讲清楚未必等于读者的讲清楚了，读者由于原来对该事物没有认识，或者虽有认识但有些偏差，因而，当读者通过文档收获的东西不完全等于写者想表达的所有内容时，就不能定义为讲清楚了。笔者建议，在撰写需求文档时，要用目标读者的角度去衡量怎样把事情交代清楚，怎样能够让目标读者方便阅读、方便理解。做到心中有读者，就能使得软件项目需求文档的质量不断有提高。 2 需求文档的涵盖范围 一般情况下，需求文档用需求模型和以用例为主体的文档相结合来表现。模型可以给读者以清晰、明确地主观印象。但因为其抽象性，不能把所有信息表达出来，更需要以文字解说的方式来补充。当一堆信息丰富的文字不分轻重缓急放在一起呈现给读者的时候，读者体会到的是杂乱，需要花很多心思去理清关系。用例在这时就应运而生，它能够帮助编写者很好地组织信息，也可能帮助阅读者快速找到需要的信息。 用例是需求，如果编写恰当，用例可以准确地对系统必须要做什么进行详细地描述。但另一方面，用例不是所有的需求，用例部详细地描述外部接口、数据格式、业务规则和复杂的公式。用例只是需要收集的所有需求中的一部分，虽然这一部分非常重要，但毕竟仅仅是一部分。业务规则、词汇表、性能目标、过程需求和许多其他方面的东西都不属于行为需求之列，因此不属于用例的范畴[1]。本文的需求文档是一个泛指，泛指所有和需求有关的文档，包括用例、业务规则、词汇表等等。 3 需求文档的两难境地 笔者在一家公司的软件部门工作7年有余，参加过5个以上不同的软件项目组，更观察了超过10个以上公司内外软件团队的工作。目前软件团队中需求文档的读者主要是用户、客户;系统分析员、需求分析员;软件开发者、程序员;测试员;项目管理者等。方方面面的人员对于需求文档的不同要求，加上需求工程师们对自己撰写的文档的一些认识和要求造成了需求文档的一些两难境地，通过一些现象表现出来。 现象一：用户代表们看完所有的厚厚一叠需求文档(主要是用例)后，觉得很茫然，好像文档所叙述的内容都没有问题，但对根据文档开发出来的软件是否是自己需要的并没有把握。 现象二：开发工程师和质量工程师们总是反映需求文档不够细致，不能体现到每个按钮、每个字段的要求。对开发和测试工程师们来说这些信息确实属于需求的一部分，而对于需求工程师们来说，这样的文档撰写、维护所耗费的精力实在是无可估量的。在一些没有专职的系统设计师的团队中，需求工程师要拿捏尺度，在需求文档和设计文档中寻找平衡点，也不是一件容易的事。 现象三：在开发团队中做熟的一些工程师们，希望每个迭代的文档更有针对性。如果每个迭代的需求文档都是在之前的需求文档上的叠加，那么他们往往要花费很多时间和精力去把那些修改之处找出来。然而，当需求工程师们，顺应大家的要求，按迭代周期撰写需求文档时，新近加入的工程师们又抱怨连连：他们没有办法，看到系统到当下最正确且及时的情况以文档来反映，当他们从0.1，0.2版本的文档阅读到0.5，1.0时，赫然发现之前所阅读并记忆的很多东西其实已经完全被摒弃或者有了天翻地覆的变化。当然，也有可能当他们读到1.0版本时，已经不记得0.2版本写了什么了。 现象四：需求工程师们把需求文档看成是一个累赘，对他们来说分析清楚需求，是一件很有挑战的工作。然而，撰写需求文档，只是一个很枯燥的工作，看上去全然没有创造性，反而吃力不讨好——没有最好的文档，总有人有不满意见。在撰写新文档上，需求工程师们可能受到流程控制、实际需要而忙碌工作于文档上，但对于一些需求变更，或者对于需求文档中二义性词句的修改，就显得不那么按部就班。由于工业化的软件开发有很多进度的要求，造成文档评审的效果和结果都有些折扣，如此一来，需求文档更成为一种鸡肋，食之无味弃之可惜。 其实，对于需求文档，方方面面的意见实在太多太杂，举不胜数。然而，需求工程师们就真的在需求文档行这道坎前束手无策，坐以待毙么?答案当然是否定的。把需求文档的撰写看作是需求工作中的重要一环，把需求文档的质量看作是自身业务水平的一个体现，需求文档一定能有起到其在软件开发中的应有作用。 4 高质量需求文档的衡量标准 需求是一种知识，知识在被转播的过程中需要一种用载体来呈现，需求文档正是这样一种载体。如果需求本身在获取的过程中已经出现质量问题，那么需求文档质量再高也只能反映有缺陷的需求;反之，如果编撰需求文档的能力非常低下，那么高质量的需求在别人眼中就成为残缺不齐的需求。因此需求文档的质量要求和需求本身的质量要求实际上是一致的。两者密不可分。