如何编写需求文档

优秀需求具有的特性－需求陈述的特征
1. 完整性
2. 正确性
3. 可行性
4. 必要性
5. 划分优先级
6. 无二义性
7. 可验证性
8.一致性
9.可修改性
10.可跟踪性
推荐的编写需求文档的指南
定义标准的文档结构
说明如何使用文档
包含一个需求概要
构造系统的业务案例
定义专业术语
安排好文档的版面使文档易读
帮助读者查找信息
使文档易于变更
推荐的需求描述指南
定义描述需求的标准模板
使用浅显、一致、简明的语言
适当地使用图解
其他需求描述辅助自然语言
定量说明需求
惟一地标识每个需求
记录需求源
需求的理由
1.定义标准的文档结构
为需求确定恰当的结构可有助于：
– 有利于读者阅读
– 最小化需求的总量；
– 理解大量信息；
– 找出与具体问题有关的需求集合；
– 发现遗漏和重复；
– 消除需求之间的矛盾；
– 管理迭代（例如延迟提出的需求）；
– 拒绝差的需求；
– 评估需求；
– 在多个项目中重用需求。
– 开发软件来支持符合通用标准的需求文档产品
定义标准的文档结构
文档一般是分层的，对于多个层次采用节和小节来组织。文档层次是分类的有用结构，确定需求文档结构的一种方式，是使用通过标题结构能够对需求语句编目的节。采用这种方式，需求语句在文档中的位置代表其一级分类。（二级分类可以通过指向其它节的链或通过属性给出。
文档结构－IEEE/ANSI1830-1993
a.引言
a.1目的
a.2文档约定
a.3预期的读者和阅读建议
a.4产品的范围
a.5参考文献
b.综合描述
b.1产品的前景
b.2产品的功能
b.3用户类和特征
b.4运行环境
b.5设计和实现上的限制
b.6假设和依赖
c.外部接口需求
c.1用户界面
c.2硬件接口
c.3软件接口
c.4通信接口
d.系统特性
d.1说明和优先级
d.2激励/响应序列
d.3功能需求
e.其它非功能需求
e.1性能需求
e.2安全设施需求
e.3安全性需求
e.4软件质量属性
e.5业务规则
e.6用户文档
f.其它需求
附录A：词汇表
附录B：分析模型
附录C：待确定问题的列表
文档结构－组织特殊信息
系统的概述和开发该系统的效益
解释所使用的技术术语的术语表
系统服务或功能需求的定义
系统特性或如可靠性、安全性等非功能性需求的定义
系统操作和系统开发过程的约束
系统的操作环境和该环境可能变更的定义
详细的系统规格说明，它被表示成表示系统组件之间关系的系统模型。
2.说明如何使用文档
效益
– 减少阅读的成本
– 明确知识要求
实施
– 明确所针对不同类型的读者
– 明确理解文档所需要的专业知识和技术背景
– 指向概述部分的指示器
– 明确第一次阅读进可以路过的部分
– 描述阅读各部分的相关顺序
3.包含一个需求概要
效益－更易于理解的需求文档
– 帮助理解概要
– 关注关键需求，有利于建立需求的优先级
– 作为文档中的需求的映射，有助于读者发现感兴趣的需求
实施
– 是重要的需求用编号的列表来表示
– 基于某种分类结构，在表格中列出不同需求
– 通过把每个主要需求表示成图上的一个结点，可以产生需求的图形化视点
4.构造系统的业务案例
效益－提供系统需求的一个理由
– 帮助评估需求变更
– 帮助理解包含特殊需求的原因
实施
–  放在需求文档引言的单独章节中
–  列出业务目标
–  给出目标系统有助于这些业务理由
5.定义专业术语
效益－避免需求文档的读者与作者之间的误解
– 帮助读者理解需求文档
– 帮助不同作者使用相同的术语
– 减少混淆
实施
–  定义一个标准的术语表
–  根据术语表修改需求文档
–  例如： 词汇表
6.安排好文档版面使文档易读
效益－－使文档易读
– 读的次数比写的次数多，因此……
– 易于评审时发现更好的问题
实施
– 使用宽的页边空白来使文本
– 节和小节的标题采用一致的格式
– 少用着重号，一致地使用着重号
– 使用表格、标号列表或数字列表来表示相关信息项的集合。
– 当许多信息项必须表示成稳定和变化两部分时，使用表格来显示共同点和不同点。
– 使用空白把方程式和文本分开，并使用不同字体来表示它们。
– 如果要描述一系列事件或一个顺序的过程，使用图表来显示过程的各个步骤。
– 不用使用复杂的图表
7.帮助读者查找信息
效益－易于用做系统参考
– 索引和目录容易使需求规格说明作为参考文档
– 索引帮助读者评审文档
实施
– 生成索引和目录
– 出现在索引中的术语应在正文中标明
– 可以使用字处理系统中的自动化工具来创建索引
8.使用文档易于变更
效益－减少需求变更的成本
– 制作和分发新的需求文档既昂贵又耗时，易于变更的文档可以改变这种情况
– 有利于及时验证文档
实施（结合“安排好文档的版面使文档易读”一起实施）
– 把文档做成活页
– 利用字处理系统的修订模式
– 写文档时，避免引用文档中的其他页码
– 确保所有图表都有标签，始终使用标签引用图表
– 保持章简短以便整章可以被用户替换
– 在单独的页上开始新的一章
– 始终根据章给页编号
– 如果有的话，使用使用字处理系统中制作图、表等的相对引用的功能。以便能够自动变更引用。
9.定义描述需求的标准模板
效益－－需求前后一致，更加易懂
– 标准使得需求易于阅读
– 标准使得需求易于收集
– 标准使得需求易于书写
实施
–  针对不同业务领域和技术使用不共的需求模板
–  对模板的使用进行详细说明（注释）
–  提供样本以供参考
10.使用浅显、一致、简明的语言
效益－－需求更加易读易懂
– 使用浅显的语言书写的需求易于阅读和理解
– 使用浅显的语言书写的需求有利于让更多的人理解需求
实施－书写规则
– 用短句
– 一个句子表达一项需求
– 不要使用术语和缩略语，除非完全确信文档的所有读者都能够明白。
– 用短段。（一个段落不应该多于七个句子）
– 尽可能使用列表或者表格来表达信息序列。
– 术语一致
– 使用“必须”、“应该”、“将”时注意它们词义的前后一致。
– 不要使用嵌套的条件从句表达需求。
– 使用主动语气而不是被动语气
– 不要试图在自然语言描述中表达复杂的关系（用图）
– 不用使用匿名引用。
– 注意拼写和语法
10.使用浅显、一致、简明的语言
除了语言之外，还有一些需求语句应该满足的特定准则。这些准则归纳如下：
原子性：每个语句都只携带单个可跟踪元素；
唯一性：每个语句都可以被惟一地标识；
可行性：在成本和进度限度内，在技术上是可行的；
合法性：在法律上是可行的；
清晰性：每个语句都可以被清晰地理解；
准确性：每个语句都是准确、精确的；
可检验性：每个语句都是可检验的，并知道如何检验；
抽象性：不强迫针对下层的特定的设计解决方案。
11.适当地使用图解
效益－－图解最适于记录需求关系
– 图解在表示关系时比文本有效得多
– 图解将大段的文本分为更小的、更易于阅读的片段
– 图解可能在对客户展示需求时重用
实施－时机
– 当某个对象由多个模块和组件组成，而你希望阐明它们之间的关系时
– 当需要表达一个系列的行为，而每个行为都有一些输入输出时。图解可以用来表述行为序列，以及在哪些地方这些行为可以并行发生。
– 当需要说明空间组织，如控制板时
– 当需要使用一些分解结构，如组织结构图
使用图解的原则
尽可能简单
避免使用意义不清的图标
应该用颜色或阴影来区分图解的不同部分或者起强调作用
不用乱用图解
12.用其他需求描述辅助自然语言
效益－－更加简明、无二义的需求描述
– 特殊符号的描述不太可能引起误解
– 对于对符号熟悉的专家更易发现问题
实施
– 决策树
– 编程语言或程序设计语言
– 代数
– 数据流图
– 时序图
– 系统模型
13.定量说明需求
效益－－无二义的表达需求
– 简明的交流方式
– 可能作为系统验收测试的基准
实施
–  定义表达这些属性的合适的度量
–  为属性决定一个合适的值
非功能需求可能使用的度量
14.惟一地标识每个需求
效益－方便引用、利于管理
– 可以用来指向相关的需求和构造可跟踪性表
– 有利于放到数据库中统一管理
– 有利于需求版本的管理
实施
–  最常用的方法是根据需求文档中包含的章节分配数字
字处理系统可以自动处理
临时的标识符解决需求无法确认的问题
15. 记录需求源
效益－需求可跟踪性
– 有利于分析和变更需求
– 有助于理解该需求存在的原因
实施
–  需求收集表中记录需求源
–  在需求数据库中也可以记录
–  不要放在需求规格说明书中
低成本需求文档编写规则
以上15种需求文档编写指南为低成本引入的方法。
16.需求的理由
效益－提高对需求的理解
– 使读者更易于理解和评估需求变更的影响
– 问题专家可以使用该理由检验需求是否与正在解决的问题一致。
实施
–  需求收集表中记录需求源
–  在需求数据库中也可以记录
–  不要放在需求规格说明书中
写文档的总的原则
一开始就定义提纲结构，最好是层次式的，并随着工作的深入不断改进。
尽可能快地写下需求，即使这些需求并不完备。
提前确定用于为文本描述分类与详细描述的属性是什么。
快速产生一个初始版本，以便立即得到反馈。
随着工作的输入不断完善需求，去掉重复部分、难以保证的设计和不一致性。
不断集思广益并进行非正式评审，快速改进版本。
向用户请教要比由“专家”分析好得多。