软件文档写作与管理

  社会的发展对软件工程师提出了越来越高的要求，不仅要求他们具备良好的知识背景、较强的动手能力，还要求他们具有很好的沟通与表达能力。从培养和训练软件工程师的书面沟通能力这一主旨出发，本书介绍了软件技术文档撰写的基本原则、常用的文档类型，以及收集信息和书写文档的策略，使学生或软件工程师按照已定义的标准格式，使用适当使用表格、图和参考文献等，书写清晰、简明和准确的技术文档和个人总结，能评审书面文档以发现各种问题，从而展现高质量的正式文档。 

社会的发展对软件工程师提出了越来越高的要求，不仅要求他们具备良好的知识背景、较强的动手能力，还要求他们具有很好的沟通与表达能力。从培养和训练软件工程师的书面沟通能力这一主旨出发，本书介绍了软件技术文档撰写的基本原则、常用的文档类型，以及收集信息和书写文档的策略，以便使读者能按照标准的格式恰当地使用表格、图和参考文献等，书写出清晰、简明和准确的技术文档和个人总结，并能评审书面文档以发现各种问题。本书要求读者具备一定的软件工程知识。

目录

第1章软件工程基础
1.1软件与软件工程
1.1.1软件定义与软件特点
1.1.2软件危机与软件工程
1.2软件过程
1.2.1瀑布模型对应的软件过程
1.2.2以架构为核心的软件过程
1.3软件过程中的文档
1.3.1软件文档
1.3.2撰写软件文档的目的与作用
1.3.3软件文档的范围及分类
1.3.4项目开发与文档的关系
1.3.5软件过程角色与文档的关系
1.3.6软件过程中的文档编制
1.3.7撰写软件文档应考虑的因素
1.3.8软件文档的管理
第2章项目规划类文档写作
2.1项目立项过程
2.2商业计划书
2.2.1商业计划书写作要求
2.2.2商业计划书内容框架
2.3可行性研究报告
2.3.1可行性研究报告写作要求
2.3.2可行性研究报告内容框架
2.4项目方案书
2.4.1项目方案书写作要求
2.4.2项目方案书内容框架
2.5项目开发计划
2.5.1项目开发计划写作要求
2.5.2项目开发计划内容框架
第3章需求类文档写作
3.1需求概述
3.2软件需求的分类
3.3需求过程
3.3.1需求分析
3.3.2需求过程的管理
3.3.3需求获取的流程
3.3.4需求管理的角色
3.4需求说明书的撰写要求
3.4.1需求文档的文字叙述要求
3.4.2对用例说明的要求
3.4.3非功能需求的说明要求
3.5需求说明书内容框架
3.6需求原型工具Axure
第4章设计类文档写作
4.1软件设计过程
4.2软件架构设计
4.2.1架构的概念
4.2.2以架构为中心的迭代开发周期模型
4.2.3领域建模
4.2.4非功能需求驱动的架构设计
4.3软件架构文档
4.3.1软件架构文档写作要求
4.3.2软件架构文档内容框架
4.4概要设计说明书
4.4.1概要设计说明书写作要求
4.4.2概要设计说明书内容框架
4.5详细设计说明书
4.5.1详细设计说明书写作要求
4.5.2详细设计说明书内容框架
4.6数据库设计说明书
4.6.1数据库设计的步骤
4.6.2数据库设计说明书内容框架
4.7用户界面设计文档
第5章测试类文档写作
5.1测试过程
5.1.1测试概述
5.1.2集成测试过程
5.1.3系统测试过程
5.2测试用例的撰写
5.2.1测试用例写作要求
5.2.2测试用例内容框架
5.3测试计划
5.4测试分析报告
第6章项目结束类文档写作
6.1部署过程
6.2用户培训计划
6.3开发组织内部的培训课程
6.4用户手册
6.4.1用户手册要求
6.4.2用户手册内容框架
6.5产品手册要求
6.6项目总结
6.6.1项目总结要求
6.6.2项目总结报告内容框架
第7章项目管理过程类文档写作
7.1项目管理过程
7.2项目风险管理
7.3时间进度管理
7.4项目估算管理
7.5项目管理过程文档
第8章质量保证文档写作
8.1软件质量保证定义
8.2软件质量保证管理
8.2.1SQA过程
8.2.2SQA偏差过程
第9章软件文档配置管理
9.1软件配置管理过程
9.1.1软件配置管理出现的背景
9.1.2软件配置管理发展现状
9.1.3软件配置管理的目的
9.1.4软件配置管理的基本活动
9.2配置管理过程规范
9.2.1配置管理计划
9.2.2实施配置管理
9.3配置管理工具
9.4软件文档的配置管理方案
9.4.1软件配置管理环境的设置
9.4.2软件配置管理机制的组成和建立
9.4.3软件配置管理活动的实施流程
9.4.4软件配置管理基本任务的相关规范
9.4.5配置管理的标识规范
9.4.6配置管理的建议
9.5需求文档变更的管理
9.5.1需求变更的原因
9.5.2需求变更的处理流程
第10章企业软件文档的管理
10.1企业软件文档分类
10.2企业软件文档管理要求
10.3企业软件文档管理流程
10.4项目文档的管理
附录A文档封面模板
附录B项目规划期文档模板
B.1可行性研究报告模板
B.2项目方案书模板
附录C需求类文档模板
C.1需求调研报告
C.2需求规格说明书
C.3用例使用场景模版与实例
C.4用例描述模板
C.5需求评审报告
C.6需求分析报告检查表
附录D文档设计模板
D.1软件架构设计说明书
D.2概要设计说明书
D.2.1模板1
D.2.2模板2
D.3详细设计说明书
D.3.1模板1
D.3.2模板2
D.4数据库设计说明书
附录E设计文档模板
E.1软件配置管理规范
E.2软件修改报告
附录F单元测试报告文档模板
附录G项目管理文档模板
G.1风险列表
G.2周报
附录H质量保证文档模板
H.1质量保证计划
H.2SQA汇总报告
H.3SQA每周报告
H.4SQA偏差报告
附录I软件文档评分标准
参考文献

前言

评论

第5章测试类文档写作
5.1测试过程5.1.1测试概述
软件测试是对软件计划、软件设计、软件编码进行查错和纠错的活动(包括代码执行活动与人工活动)。测试的范围是整个软件的生存周期，而不限于程序编码阶段。据统计测试工作量要占软件开发总成本的40％~50％，测试的目的是确保软件的质量，尽量找出软件错误并加以纠正，而不是证明软件没有错。在程序员对模块的编码完成之后先做程序测试，再做单元测试，然后再进行集成(综合或组装)测试，系统测试，验收(确认)测试，其中单元测试的一部分在编码阶段就开始了，测试横跨开发与测试两个阶段，又有不同的人员参加，测试工作本身是复杂的。1. 测试的目标测试的目标是为了发现程序中的错误而执行程序的过程。好的测试方案是极可能发现迄今为止尚未发现的错误的测试方案，成功的测试是发现了至今为止尚未发现的错误的测试。2. 测试的原则(1) 测试前要认定被测试软件有错，不要认为软件没有错。(2) 要预先确定被测试软件的测试结果。(3) 要尽量避免测试自己编写的程序。(4) 测试要兼顾合理输入与不合理输入数据。(5) 测试要以软件需求规格说明书为标准。(6) 要明确找到的新错与已找到的旧错成正比。(7) 测试是相对的，不能穷尽所有的测试，要根据人力物力安排测试，并选择好测试用例与测试方法。(8) 测试用例会反复使用，以重新验证纠错的程序是否有错。3. 软件测试技术按照测试过程是否在实际应用环境中来分，测试技术分为静态分析与动态测试。1) 静态分析技术不执行被测软件，可对需求分析说明书、软件设计说明书、源程序做结构检查、流程分析、符号执行来找出软件错误。2) 动态测试技术当把程序作为一个函数，输入的全体称为函数的定义域，输出的全体称为函数的值域，函数则描述了输入的定义域与输出值域的关系。这样动态测试的算法有： ① 选取定义域中的有效值，或定义域外的无效值。② 对已选取值决定预期的结果。③ 用选取值执行程序。④ 观察程序行为，记录执行结果。⑤ 将④的结果与②的结果相比较，不吻合则程序有错。动态测试既可以采用白盒法对模块进行逻辑结构的测试，又可以用黑盒法做功能结构的测试，接口的测试，都是以执行程序并分析执行结果来查错的。4. 测试方法测试方法主要有白盒法与黑盒法。1) 白盒测试法白盒法是通过分析程序内部的逻辑与执行路线来设计测试用例并进行测试的方法，白盒法也称逻辑驱动方法。白盒法具体的测试用例设计方法有： 语句覆盖、分支(判定)覆盖、条件覆盖、路径覆盖(或条件组合覆盖)，主要目的是提高测试的覆盖率。白盒测试法的前提是可以把程序看成装在一个透明的白盒子里，也就是完全了解程序的结构和处理过程。这种方法按照程序内部的逻辑测试程序，检验程序中的每条通路是否都能按预定要求正确工作，白盒测试又称为结构测试。2) 黑盒测试法黑盒法是功能驱动方法，把程序看成一个黑盒子，仅根据I/O数据条件来设计测试用例，而不管程序的内部结构与路径如何。黑盒法具体的测试用例设计方法有： 等价类划分法，边界值分析法，错误推测法，主要目的是设法以少测试数据子集来尽可能多地测试软件程序的错误。黑盒测试是在程序接口上进行的测试，它只检查程序功能是否能按照规格说明书的规定正常使用，程序是否能适当地接收输入数据产生正确的输出信息，并且保持外部信息的完整性。黑盒测试又称为功能测试。黑盒测试是基于系统需求规格，在不知道系统或组件的内部结构的情况下进行的测试。通常又将黑盒测试叫做基于规格的测试(SpecificationBased Testing)、输入输出测试(Input/Output Testing)、功能测试(Functional Testing)。测试的角色和职责如表51所示。