[课业] 15 | 软工 | 需求文档化与验证

为什么文档化需求

1. 项目是team work，人多就需要沟通交流，而项目越大，沟通成本越大
2. 项目经理、架构师、设计师、程序员、维护人员等之间都需要交流
3. 文件的使用场景：项目引入新人，要让他快速了解这个项目，跟上旧人的工作进度
4. 为什么要使用规范化文档
   当文档不规范时，会降低沟通效率
   同样的规范，同一个模版，相同的表达方式，降低了沟通的困难，提高效率
5. 其他沟通办法
   开会：相对效率低，但是可以解决特定疑问（当面解决，有反馈的解决）
   代码：代码的阅读
6. 文档规格化作为配置管理产物中，用例文档与软件需求规格文档(SRS)是很重要的

用例文档

1. 用例文档是用户级别的
2. 用例以交互的形式表达需求
   用例是需求的一种表达和组织方式，是系统与外界交互序列、不同的交互序列（不同场景），服务于一个业务目标
3. 用例文档在用户的角度以用例文本为主描述软件系统与外界交互
4. 用例文档的基本职责是把问题域信息与需求传达给软件系统解决方案的设计者
5. 需求文档的最终目的：将前面收集来的各种问题域描述转化为利于设计人员处理的文本
   用例文档是一个中间步骤
   在描述需求时，需要一层层抽象（业务需求，用户需求，系统级需求）才能给设计人员
   难以直接将需求直接描述成系统级层次，先描述成用例（用户需求层次）
6. 示例
   
   注意：
   用例图描绘的是大致印象；用例描述是仔细地描述
   如果有大的用例，先画大用例，再画相关子用例
   如果用例太多，画用例图画不下，可以画用例列表
7. 用例只是一种组织方式，并非只有唯一答案
   用例的正常流程的异常流程如果很复杂，可以组织到别的地方（比如自成一个用例）

软件需求规格说明文档(SRS- Software Requirement Specification)

1. 软件需求规格说明文档是系统级的
2. 软件需求规格说明文档在软件产品的角度以系统级需求列表的方式描述软件系统解决方案
3. 用例与系统规格

用例	系统规格
侧重于交流过程（即“输入为何，输出为何”）	侧重于独立需求（完整地描述交互中，软件系统的处理细节，将所有软件系统处理细节描述清楚）
以一次交互为基础 （如“用户登录”）	以一次交互中的软件系统处理细节为基础 （用户登录时“界面怎样、如何跳转、输入什么信息、显示什么信息等）（无歧义地描述）

4. 示例
   
   主体为功能需求

文档化需求的注意事项

技术文档写作要点

1. 简洁
2. 精确
3. 易读（易查询）
   有效使用引言、目录、索引等能够增强文档易读性的方法
   使用系统化方法组织内容信息，提供文档内容等可读性
4. 易修改
5. 注意：
   技术文档的主要用途是查询，技术文档规模大时，不易读往往意味着不易查询
   系统化方法如模版：形式类似，组织形式一致，可推断出内容信息等位置等

系统化方法

1. 使用相同的语句格式来描述相似、关联的信息
2. 使用列表或者表格来组织独立、并列的信息
3. 使用编号来表达繁杂信息之间的关系，包括顺序关系、嵌套关系和层次关系
   对图、表进行编号
   对文档的章节进行编号
   对信息内容进行标识和编号
4. 词汇要求
   不要使用含有歧义的词汇（形容词一般不用）

歧义词汇	改进方法
可接受的、足够的	具体定义可接受的内容，说明系统怎样判断“可接受”或“足够”
依赖	描述依赖的原因，数据依赖？服务依赖？资源依赖等
有效的	明确“有效”所意味的具体实际情况
快的、迅速的	明确指定系统在时间或速度上可接受的最小值
灵活的	描述系统为了响应条件变化或者需求变化而可能发生的变更方式
改进的、更好的、优越的	定量说明在一个专门的功能领域内，充分改进