社会的发展对软件工程师提出了越来越高的要求，不仅要求他们具备良好的知识背景、较强的动手能力，还要求他们具有很好的沟通与表达能力。从培养和训练软件工程师的书面沟通能力这一主旨出发，本书介绍了软件技术文档撰写的基本原则、常用的文档类型，以及收集信息和书写文档的策略，以便使读者能按照标准的格式恰当地使用表格、图和参考文献等，书写出清晰、简明和准确的技术文档和个人总结，并能评审书面文档以发现各种问题。本书要求读者具备一定的软件工程知识。
前言
软件文档随着软件的产生而产生，随着软件工程的提出和发展而不断得到规范，并且软件文档也成为软件工程各个阶段里程碑的重要标志之一。但在实际软件开发过程中，由于人为因素以及时间和成本的限制，导致软件文档资料通常既不完整也不合格，进而对软件开发和后期维护造成影响。
本书旨在将软件工程的基础理论、实践和文档写作紧密结合，以提供一个统一分层的软件文档写作体系； 将有关软件工程理论、软件文档写作方法的叙述、分析和应用有机地结合，使之形成一个较完整的软件文档写作方法体系； 对软件文档管理给予系统的介绍，从而充实和丰富传统的软件文档写作。
本书是作者十多年来从事软件工程教学、理论与实践研究的学习心得和工作总结，且汇入了一些企业的软件文档规范和阅读国内外大量相关著作和论文的体会。它以分析的观点、实践的角度，站在开发与应用的立场来进行讨论，希望不仅说明软件文档“是什么”，还进一步分析“为什么”，且讨论“如何做”，使读者不仅能“知其然”，还能“知其所以然”，懂得“如何应用”。它不仅包括了软件工程各个阶段的文档，还从质量保证和配置管理的角度说明对文档的管理。
全书共分10章，第1章介绍软件工程基础以及软件文档和软件过程之间的关系； 第2章介绍项目规划类文档写作，包括商业计划书、可行性研究报告、项目方案书和项目开发计划等； 第3章介绍需求类文档写作，主要涉及需求规格说明书； 第4章介绍设计类文档写作，包括架构文档、概要设计说明书、详细设计说明书、数据库设计说明书和界面设计文档等； 第5章介绍测试类文档写作，包括测试用例、测试计划和测试分析报告； 第6章介绍项目结束类文档，包括用户培训计划、用户手册、产品手册和项目总结报告等； 第7章介绍项目管理过程类文档，包括项目风险管理、时间进度管理、估算管理和项目的月报与周报等； 第8章介绍质量保证相关文档； 第9章介绍软件文档配置管理的方案，对软件文档进行版本控制； 第10章介绍企业软件文档的管理； 最后是附录，给出了若干软件文档的模板供读者参考。
本书在编写过程中力求语言通俗易懂，文字简洁明了，便于自学者阅读，除可作为高校计算机专业和软件工程专业的教材外，也可供从事计算机工作的工程技术人员及其他自学者参考。
本书的手稿已在软件学院对本科生和研究生讲授了多次，他们有的阅读了原讲义，并提出过意见。
对于书中的许多内容，作者的多届研究生、本科生曾从各个不同的方面、以不同的形式做了许多工作。在此，一并向他们表示诚挚的谢意。
诚如前面所说，书中的许多方面是作者的学习与实践体会，有的内容是作者的研究心得，再加之作者才学疏浅，水平与能力有限，因此书中见仁见智之说、不妥或不足之处，恐在所难免，切盼学术界同仁、软件从业人员和各方读者不吝赐教。
作者
2016年8月
第3章需求类文档写作
3.1需求概述
作为技术人员，大家更多关注的是技术，但软件需求在很大程度上决定了软件是否正确，需求确定后不管如何实现，功能和质量给客户直接带来的价值远远比技术直接带来的价值要高。因此，做正确的事比正确地做事更重要。错误需求带来的问题一直是各个软件公司项目失败的首要原因，因为获得需求是个复杂的过程，要在实践中不断地学习，提高需求分析的能力。需求有以下三个层次。
1. 业务需求
描述客户的高层次目标，通常问题定义本身就是业务需求的表征。这种目标通常体现在两个方面。
（1） 问题： 解决企业/组织运作过程中遇到的问题，如设备管理混乱、用户投诉量大、客户流失率高等。
（2） 机遇： 抓住外部环境变化所带来的机会，以便为企业带来新的发展，例如电子商务、网上银行、物联网等。
业务需求就是系统目标，它是以业务为导向、指导软件开发的高层次需求。这类需求通常来自高层，例如项目投资人、购买产品的客户、实际用户、市场营销部门或产品策划部门。业务需求从总体上描述了为什么要开发系统（why），组织希望达到什么目标，一般在可行性研究报告中反映，也可使用前景和范围（vision and scope）文档来记录业务需求，这份文档有时也被称做项目章程（Project Charter）或市场需求（Market Requirement）文档。组织愿景是一个组织对将使用的软件系统所要达成的目标的预期期望，如“希望实施CRM后公司的客户满意度达到90％以上”就是一条组织愿景。
2. 用户需求
用户需求是指用户要使用产品完成什么任务，通常是在问题定义的基础上进行用户访谈、调查，对用户使用的场景进行整理，从而获得来自用户角度的需求。用户需求必须能够体现软件系统将给用户带来的业务价值，或用户要求系统必须完成的任务，也就是说用户需求描述了用户能使用系统来做些什么（what），这个层次的需求是非常重要的。
作为需求捕获阶段的主要产物，用户需求主要具有以下特点：
（1） 零散。用户会提出不同角度、不同层面、不同粒度的需求，而且常常是以一句话形式提出的，如通过电话、短信等非正式方式提出的需求。
（2） 相互矛盾。由于不同用户处于企业/组织的不同层面，可能会出现盲人摸象的情况，导致需求的片面性。
因此，还需要对原始需求进行分析和整理，从而得出更加精确的需求说明。用例是表达用户需求的一种有效途径。
3. 软件需求
由于用户需求具有零散、片面的特点，因此需求分析人员还需要对其进行分析、提炼、整理，从而生成可指导开发的、更准确的软件需求，软件需求是需求分析与建模的产物。
软件需求是需求的主体，它是设计具体解决方案的依据（how），其数量往往比用户需求高一个数量级。这些需求记录在软件需求规格说明（Software Requirements Specification，SRS）中。SRS完整地描述了软件系统的预期特性，SRS一般被当作文档保存，设计、实现、测试、质量保证、项目管理以及其他相关的项目过程都要用到SRS。
3.2软件需求的分类
软件需求可分为功能需求、质量需求、约束条件三种类型，质量需求和约束条件也叫非功能需求。
1. 功能需求
功能需求规定必须在产品中实现的软件功能，用户利用这些功能来完成任务，满足业务需求。
对于功能需求而言，最关键的是如何对其进行组织，否则一句话的描述就会十分分散，很难保证开发人员逐一理解和满足这些要求。
在传统的方法论中，会以系统→子系统→模块→子模块的层次结构来组织，和程序的结构相对应，但这样会割裂用户的使用场景。为了解决这个问题，现代需求理论更加强调需求分析人员从用户的角度将系统理解成一个黑盒子，从横向的使用视角来整理需求。
2. 质量需求
质量需求不同于产品的功能描述，它从不同方面描述产品的各种特性。这些特性包括可用性、可移植性、性能、安全等，它们对用户或开发人员都很重要。
质量需求描述有两个常见问题。
（1） 信息传递的无效性： 在很多需求规格说明书中，会通过一个名为性能需求的小节来说明非功能需求，列出诸如高可靠性、高可用性、高扩展性等要求。但是很多开发人员根本就不看这些内容，因为这样的定性描述缺乏判断标准，故这种信息传递方法是无效的。
（2） 忽略了质量需求的局部性： 经常会看到诸如“所有的查询响应时间都应该小于10s”的描述，但是当用户查询的是年度统计数据时，这样的需求是较难实现的，因此开发人员就会忽略和不理会这样的需求，最终的结果就是导致它成为了摆设。因此更科学的做法是利用具体的应用场景来描述。
……
书单推荐
