讲课视频在线视频

下面我们介绍

如何撰写需求文档

撰写软件需求规格说明的目标

是为了围绕应用领域

与待开发的系统进行沟通

形成一个具有

一定法律效力的合同文档

并以供需双方就系统内容

达成的共识

清楚的描述软件在什么情况下

需要做什么

以及不能做什么

通过定义以系统的输入输出

以及从输入到输出

之间的转换的方式

来描述系统的功能性的需求

描述经过干系人磋商后

达成共识的非功能性的需求

及其评估指标

我们一般可以

参考需求定义的模板

覆盖标准模板中

定义的所有相关条目

并将需求作为后续的

软件评估的依据

和需求变更的基准

需求文档需要有

一定的逻辑组织结构

目前（01：22）提供的模版是

被最广泛应用的

文章组织形式之一

除此以外

典型的需求文档的组织形式

还包括可以按照系统

能够响应的

各种外部环境的情况来组织

比如对于一个

飞机着陆管理系统来说

按照飞机着陆时的环境条件如

风速 燃料余量 跑道长度等

来组织需求的撰写

也可以按照

系统的功能特征来组织

比如对于一个电话系统来说

按提供给客户的功能特征来组织

比如呼叫转移 来电屏蔽

电话会议等

也可以按照系统对于外部请求的

响应方式来组织

比如对于一个工资管理系统

按请求响应的方式是

工资条生成请求

成本计算

打印税单等等

也可以按照所管理的

外部数据对象的类型来组织

比如对图书管理系统

按所管理的书籍的类型

来组织需求的撰写

也可以按照用户的类型来组织

比如对一个项目管理系统

可以按照经理人 技术人员

管理人员来组织系统的需求

还可以按照

软件的工作模式来组织

比如对一个文档编辑器

可以按照文档编辑的时候的

页面布局分为大纲模式分页模式

普通文档编辑模式等等

最后还可以按照

子系统划分来组织

对一个飞行器管理系统

我们可以分为命令控制子系统

数据处理子系统

通信子系统 设备管理子系统等

所以需求文档的组织形式

应该是按照待设计的系统

它本身的需要按照合理的

有逻辑的方式来组织

软件需求规格说明的风格

主要包括

描述性的自然语言文本

用例模型

以及从需求数据库中生成的方式

描述性的自然语言文本

最常见的是目前

以敏捷方法中用户故事为主的

简洁的文本描述

它目前仍然是最流行的

一种描述性的手段之一

需求规格说明

也可以从用例模型产生

从用例到需求

规格说明之间的关系

可以是看成

一个双向的可逆的过程

如果我们用用例

来表示需求模型

那反过来如果我们

先建立了用例模型的话

就可以逆向的

生成需求的完整的集合

也可以在工具的支持下完成

在商业的需求数据库中

也有部分内置的功能

通过对需求的列表进行筛选

生成我们想要的

需求规格说明的文档

尤其是以产品线

或者产品线家族类的

产品的需求管理为例

根据这类需求的

规格说明数据库中的选项

我们可以生成

特定产品的需求规格说明

此外我们还可以混合多种模型

比如将特征模型

和用例模型相结合

生成需求规格说明

那么后边说到的两种

往往都是要通过内嵌模板

加上工具来完成的

对不同规格的软件开发项目

需求规格说明的方式

可以是不同的

考虑以下的两种具体项目场景

对一个小型项目

有一名程序员

经过两个月的开发完成的项目

往往程序员直接可以和用户对话

写两页纸的备忘录供查

就已经足以支持项目的开发任务

而对一个大型项目

有50名程序员

经过两年的开发完成

就需要专门的团队

进行需求建模与分析

撰写详尽的需求规格说明

仔细分析两个项目的差别

我们就会发现

他撰写需求的目的

管理的视角和读者都是不同的

对小型项目来说

撰写需求规格说明的目的

是为了提升程序员

对问题领域的了解

并反馈给用户

而对项目B来说

撰写需求规格说明的目的

是为了把所有相关的细节

沟通给参与项目的

所有的研发人员

因此项目的详细程度

决定了人们对问题的理解的

精确性和详细程度

从管理的角度来看

项目A的资源是已经固定的

无论文档的如何撰写

资源都将是不会再改变的

但对于项目B来说

需要根据规格说明中的

功能点工作量来分配人员和时间

对项目任务进行规划

因此文档变得非常的重要

是很多后续工作的参照依据

从读者来看

项目A因为参与的人少

因此它的读者仅仅是

撰写备忘录的作者自身

以及需要和他确认的客户

而客户在这里

只需要了解工作的要点就可以了

两者遇到问题的时候

可以随时沟通

但对项目B来说则大不相同

因为团队人数较多

后续的测试人员

相关的管理人员

都需要随时参考需求规格说明

对项目的进度进行控制

对项目的质量进行把握

因此需求规格说明

也许成了整个团队

唯一的共同的沟通媒介

它的地位就不一样了

我们需要采用更审慎的方法

来撰写和管理需求规格说明

需求规格说明的撰写者

可以使项目的招标方

也可以是项目的投标方

或者部分系统研发人员

当然也可以由多方共同商讨完成

不同类型的需求规格说明

适合不同类型的项目

小型的项目

采用描述性的文本描述已经足够

它适合微型小型产品的

非正规的描述性的说明

它所需要的

是有良好写作能力的需求分析师

对大中型项目来说

我们既可以采用用例建模的方法

也可以通过需求的数据库来生成

它是适合具有产品线的

软件系统的正式的需求规格说明

对用例模型的使用者

分析师需要有建模能力

有好用的建模工具

也要有一定的过程规约

对需求数据库的使用者就需要有

数据库管理能力的需求分析师

对中小型项目

可以采用混合模型

它适合对单个产品进行定义

采用混合模型需要分析师

有良好的写作功能

具备数据库管理

和一定的需求工程的基础知识

也要有一定的建模能力

也就是依赖他混合模型

所涉及的各种模型

还需要具备相应的能力

Fred Brooks

在《人月神话》中

描述了将用户手册

作为需求规格说明书的做法

在苹果的第一台电脑

编码工作开始之前

据说用户手册就已经写好了

这些早期的成功故事说明

用户手册作为需求规格说明

是一种性价比较高的

一箭双雕的做法

通过撰写用户手册

我们同时获得了需求规格说明书

和用户手册两种置评

而且用户手册作为需求规格说明

对于和用户交互

比较强的系统来说是非常有效的

这样的系统往往是

由人机交互来驱动

好的用户手册也描述了

所有相关用例的场景

但是用户手册作为需求规格说明

也有它的一定的局限性

首先用户手册中

往往不会提到非功能性需求

那些不和用户直接交互的功能

也会较难设计

比如函数计算 过滤器

翻译工具等等

我们先来看看

常见的用户手册的大纲

在用户手册中

首先我们要介绍产品的总览

和它的基本工作原理

给出术语和基本的产品特征

给出展示或者报表格式的

一个总揽并介绍手册的大纲

之后我们就开始按照使用的场景

从开始使用系统到样例运行

到帮助菜单

到系统的操作模式

从命令行对话框和报告逐一遍例

最后介绍系统的高级特性

然后给出系统命令的文法

和可能的选项

需求规格说明书的用户

包括客户和终端用户

系统分析师 开发人员

测试人员 项目管理人员等等

客户和终端用户是需求的提供者

我们要保证需求的满足

符合他们的需要

而市场人员和销售人员

他们需要根据用户的要求

并以有竞争力的系统产品

管理产品的发布

软件产品的开发人员

通过了解系统要做什么

而给出系统的开发和实现方案

并最终实现系统

测试人员要参考需求

进行系统的测试验证

通过测试和用户征询这种方式

对系统的质量进行评估

项目管理人员

需要参照需求规格说明

来控制和度量项目的进展

对项目在不同的国家和地区

进行实施

需要基于产品的核心部分

补充在当地运行所需的

特殊的特性

需求规格说明

要覆盖软件产品的功能

外部接口 性能

质量属性 设计约束

而不应该包括项目的开发计划

产品的质量保证计划

和具体的设计方案

一个高质量的需求规格说明

是所有需求的集合

它描述产品要提供的所有的功能

是软件系统解决方案的

合同的基础

是测试计划的参考依据

它需要定义产品需求的度量标准

是后续产品需求跟踪的先决条件

它会影响产品的开发项目计划

但是在需求规格说明中

不可以包括项目的开发计划

产品的质量保证计划

和具体的设计方案

需求规格说明的质量

要从以下几个方面进行评价

正确性 无歧义性

完整性 可测试性

可修改性 可跟踪性

易理解性 一致性

以及有序性等

需求规格的正确性

是指它真正表达了

干系人的需求

也没有引入不必要的噪声需求

无歧义性是指

对每一个需求项

都只有一种合理的解释

不会导致误解

需求的完整性

是指它涵盖了所有必要的功能

也给出了系统不应具有的行为

在概念上具有完整性

覆盖了所有可能的收入情况

在结构上也具有完整性

没有尚未添加的部分

需求的可测试性是指

每条需求它都是可证明的

有一个测试其满足程度的过程

需求的可跟踪性

是指需求的来源清楚

每条需求都有唯一的索引号

以备未来的引用

需求的可修改性是指

从结构和相互引用的逻辑上

具有清晰的条例

确保需求项的修改

不会面临太大的困难

引入新的问题

需求的易理解性

是指它可以被非专业人士

阅读理解

需求的一致性是指需求的说法上

不会存在自相矛盾的情况

术语的使用和引用

也是一致的 连贯的

需求的有序性

是指需求之间

按照重要程度或者稳定性

排有优先级的次序

建立高质量的需求规格说明

是未来项目成功的必要保证之一

但是建立完美的需求规格说明

也是不必要不现实的

从右边的图中我们可以看到

在这些评价指标之间

是存在着一定的制约和平衡关系

比如（16：53）

如果我们吉利的缩小（16：57）

那么就有可能

引入重复的溶于的说法

除了前面提到的

几个规约的评价指标以外

我们还应该注意

保证需求的规约是简洁的

那什么样的需求描述是简洁的呢

首先它应该每一条需求

只描述系统的一个独立的特征

除了必要的信息以外

不应包含其他的信息

要用清晰简单

容易理解的词来表述

避免使用

“应该”“可以”“可能”

之类的不确定的词汇

例如在急救电话的需求描述中

有以下两种说法

首先急救电话的响应

应本着先到先得响应的原则

还有一种说法是

急救电话应按照其拨入的次序

存入一个先入先出的

等待队列当中

并且按照进入队列的次序

逐一应答

这二者之间前一种说法

相对后者是相对简洁的

建议使用前一种说法

使用需求数据库的时候

创建任何类型的需求规格说明

都优先通过需求数据库

来进行生成

所有的修改

不要直接在规格说明上进行

而是首先修改数据库中的

需求相关数据

然后从新生成需求规格说明

基于子系统划分

来组织需求规格说明

就如图中的分层结构

我们将整体的系统需求描述

按不同力度不同层次的子系统

组织相关的内容

然后为每个子系统

单独撰写相应的需求描述

这种分层结构

可以包含要开发的软硬件的模块

需求规格说明可以按照

预先定义好的模板

来组织章节的内容

模板的存在

使撰写统一标准的

需求规格说明变得非常简单

也有利于质量保证人员

定义需求规格说明的评估指标

模板即可以用于撰写业务需求

也可以撰写系统需求

当我们把模板嵌入到

需求工程工具中时

就可以自动或者半自动的

从需求数据库

或用例模型生成需求规格说明

这里给大家介绍一下（19：52）的

需求规格说明的模板

从右边的文档结构

大家可以看到

在（19：57）建议的

需求规格说明模板中

我们首先要介绍

项目的基本范围和目标

给出术语的定义

然后从总体上描述一下

系统的外部接口

相关的用户 软硬件平台

以及操作和节点上的一些要求

之后则是要对系统的特殊的功能性

和非功能性的需求

给出详细的描述

在（20：58）模板中

第三部分是最关键的内容

也就是对系统需求的详细的描述

这里又细分为

外部接口需求 功能性需求

性能需求 设计约束

以及软件系统的属性等等

其中外部接口需求包括

用户接口 硬件接口

软件接口和通信接口

而功能性的需求则包括

可以通过系统的操作模式

用户的分类

特征的分类来组织

性能需求主要是

定义那些可测量的

可以度量的性能指标

设计约束

则从依从性需求

硬件限制等等

给出在系统的设计过程中

需要注意的

来自外部环境的约束条件

软件系统的属性则是给出了

质量相关的属性

比如可靠性可用性

安全可维护性和一致性等方面

需求规格说明模板的运用

能够提高需求撰写的效率

再有参照模板的情况下

我们相当于有了

一个完整的检查表

这样不容易遗漏重要的需求信息

但模板的运用也有它的缺点

那么如果我们仅仅为了满足

标准的要求

而填写模板的所有章节

在一些不相关的章节

我们就会加入一些

不是很有意义的内容

而读者在阅读文档的时候

很难将这些没有意义的文字

和真正的重要的需求区分开来

需求撰写主要出于以下的目标

首先是在干系人之间沟通需求

其次建立合同约定

为后续的验证提供基准

为后面的需求变更提供参考

需求的规约可以给

技术和非技术的用户来使用

因此我们应该尽快的

开始撰写需求

产生一个初始的版本

来获取用户反馈

确定哪些属性

可以用于进一步细化分类需求

将其定义到需求的列表当中

在遇到问题的时候直接询问用户

往往比咨询场外的专家更为有用

在撰写需求的时候

要遵循以下法则

首先使用简单直接的语言

让非技术人员能够读懂

其次撰写可测试的需求

为需求的验证提供帮助

使用定义好

并已经达成共识的术语

一次只写一项需求

保持需求项之间的独立性

由于项目的需求有很大的不同

因此投放在需求撰写中的

代价和时间应该是

和需求可能造成的影响成正比的

获取到原始需求之后

我们应该本着一种态度是

随时准备迎接需求的变化

由于越多的干系人参与需求获取

我们就获得越多的需求特征

但是我们不能通过

减少干系人的方法

来解决这个问题

因为干系人代表着

一个独特的视角

而且干系人

有改变他们想法的权利

我们不要总是追问

这是你最终的需求吗

我们应该把变化

看成是改进系统的机会

而不是威胁项目的一个危险