开发管理 · 文档与需求：七作用、三分类、五特征

先把定义抠准：所谓文档，是指某种数据媒体和其中所记录的数据。它具有永久性，并可以由人或机器阅读，通常仅用于描述人工可读的东西。在软件工程中，文档常常是用来对活动、需求、过程或结果进行描述、定义、规定、报告或认证的任何书面或图示的信息。注意「永久性」「人工可读」这几个关键词，判断题爱抠。

文档在产品开发过程中起着重要作用，原文列了 7 项作用。第一，管理依据：每一阶段计划安排的定期报告提供了项目的可见性；开发文档规定若干个检查点和进度表，使管理者可以评定项目的进度，如果开发文档有遗漏、不完善或内容陈旧，管理者将失去跟踪和控制项目的重要依据。

第二，任务之间联系的凭证：大多数软件开发项目被划分成若干个任务并由不同小组完成——学科专家建立项目、分析员阐述系统需求、设计员制定总体设计、程序员编制代码、质保专家评价系统——这些人员需要的互相联系是通过文档资料的复制、分发和引用实现的，比如分析员向设计员提供正式需求规格说明，设计员向程序员提供正式设计规格说明。

第三，质量保证：文档的编制使开发人员对各个阶段的工作都进行周密思考、全盘权衡、减少返工，并且可在开发早期发现错误和不一致性，便于及时纠正。第四，培训与参考：使系统管理员、操作员、用户、管理者和其他有关人员了解系统如何工作、如何使用系统。第五，软件维护支持：记录开发过程中的有关信息，便于协调以后的开发、使用和维护，维护人员需要软件系统的详细说明来熟悉系统、找出并修正错误。

第六，历史档案：文档记载系统的开发历史，可使有关系统结构的基本思想为以后的项目利用，有助于把程序移植和转移到各种新的系统环境中。第七，销售可能：便于潜在用户了解软件的功能、性能等各项指标，为他们选购软件提供依据。七个作用数清楚，多选题要能认全。

按照文档产生和使用的范围，软件文档大致可分为 3 类：开发文档、管理文档、产品文档。这三个名字一字不差——练习题原题就是「软件文档按用途分为开发文档、产品文档和什么三类」，选项放测试文档、用户文档、维护文档来捣乱，答案是管理文档。注意干扰项里「用户文档」最像答案，但原文的分类里没有这个词，别被带偏。

开发文档是描述软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的一类文档，也包括软件的详细技术描述，比如程序逻辑、程序间相互关系、数据格式和存储。基本的开发文档包括：可行性研究和项目任务书；需求规格说明；概要设计说明；详细设计说明，包括程序和数据规格说明；项目开发计划；软件集成和测试计划；质量保证计划、标准、进度；安全和测试信息。

产品文档规定关于软件产品的使用、维护、增强、转换和传输的信息，起三个作用：为使用和运行软件产品的任何人规定培训和参考信息；使得那些未参加开发本软件的程序员维护它；促进软件产品的市场流通或提高可接受性。它的读者三类：用户、运行者、维护人员。基本的产品文档包括：培训手册；参考手册和用户指南；软件支持手册；产品手册和信息广告；维护修改建议。

管理文档建立在项目管理信息的基础上，从管理的角度规定涉及软件生存的信息，包括：项目开发计划、测试计划；开发过程的每个阶段的进度和进度变更的记录；软件变更情况的记录；相对于开发的判定记录；开发人员职责定义；测试报告、开发进度月报；项目开发总结。做个辨析：测试计划既在开发文档里出现也在管理文档里出现，这是原文的写法，别纠结，按选项对应。

对，软件文档从用途上还可以分为内部文档和外部文档。内部文档包括项目开发计划、需求分析、架构设计说明、详细设计说明、构件索引、构件成分说明、构件接口及调用说明、类索引、类属性及方法说明、测试报告、测试统计报告、质量监督报告、源代码、文档分类版本索引和软件安装打包文件等。外部文档主要包括软件安装手册、软件操作手册、在线帮助、系统性能指标报告和系统操作索引等。判断题抓「安装手册属于外部文档」这种配对。

文档计划可以是整个项目计划的一部分或是一个独立的文档，编制计划的工作应及早开始，对计划的评审应贯穿项目的全过程。文档计划一般包括这几方面：列出应编制文档的目录；提示编制文档应参考的标准；指定文档管理员；提供编制文档所需要的条件，落实文档编写人员、所需经费及编制工具等；明确保证文档质量的方法，如评审、鉴定等；绘制进度表，列出各阶段应产生的文档、编制人员、编制日期、完成日期、评审日期。

好的软件文档要求具备 5 个特征。第一，针对性：文档编制前应分清读者对象——管理文档主要面向管理人员，用户文档主要面向用户，这两类文档不应像开发文档那样过多地使用软件的专业术语。第二，精确性：行文应当十分确切，不能出现多义性的描述，同一课题几个文档的内容应当协调一致、没有矛盾。第三，清晰性：力求简明，如有可能配以适当的图表。第四，完整性：任何一个文档都应当是完整的、独立的、自成体系，不要在文档中出现转引其他文档内容的情况。第五，灵活性：根据具体的软件开发项目决定编制的文档种类，不能相同看待。

练习题的选项是及时性、准确性、随意性、完整性，答案是随意性——它根本不在原文的五特征里。注意题干里给的「及时性」「准确性」是干扰项的伪装，原文写的是「针对性」「精确性」，但题目把它当陪衬，真正要你挑出来的是那个不靠谱的「随意性」。做题口诀：五特征里没有的词就是不选的词。

先立背景：随着客观条件的变化和客户对软件或业务理解的加深，会产生很多新的软件需求，项目经理需要经常面对需求变更。需求管理的目的就是控制和维持事先约定，保证项目开发过程的一致性，使用户能够得到他们最终想要得到的软件产品。它涉及两个方面：需求变更、需求跟踪。

需求变更是指在软件开发过程中，用户确定软件需求之后，由于各种客观和主观条件的变化，用户增加了新的需求或改变了原有需求。进行需求变更控制的主要依据是项目计划、变更请求和反映项目执行状况的绩效报告——这三个依据要背。软件开发机构通常采取两类措施。第一类，项目启动阶段的变更预防：对一个需求分析做得很好的项目来说，基准文件定义的范围越详细、清晰，用户跟项目经理的分歧就越少；如果需求做得好，文档清晰且有客户签字，那么后期客户提出的变更超出了合同范围，就需要另外处理。

第二类，项目实施阶段的需求变更。成功项目和失败项目的区别就在于项目的整个过程是否是可控的，项目经理应该树立一个理念：「需求变更是必然的、可控的、有益的」。控制需求变更注意四点：一，需求一定要与投入有联系——在项目的开始，无论开发方还是出资方都要明确：需求变，软件开发的投入也要变；二，需求的变更要经过出资者的认可，使需求的变更有成本的概念；三，小的需求变更也要经过正规的需求管理流程——正是嫌麻烦不走流程，才使需求逐渐变为不可控，最终导致项目的失败；四，还要注意沟通的技巧，需求变更可能来自客户方也可能来自开发方，项目经理需要采用各种沟通技巧来使项目的各方受益。

需求跟踪是指在软件需求管理的过程中定义需求变更流程，分析需求变更影响，控制变化的版本，维护需求变更记录，跟踪每项需求状态。它有五大活动。第一，确定需求变更控制过程：制定一个选择、分析和决策需求变更的标准过程，所有需求变更都需遵循此过程。第二，进行需求变更影响分析：评估每项需求变更对项目计划安排和其他需求的影响，并评估完成相关任务需要的工作量。

第三，建立需求基准版本和需求控制版本文档：需求基准是项目各方对需求达成一致认识时刻的一个快照，之后的需求变更遵循变更控制过程即可。第四，维护需求变更的历史记录：记录变更日期、原因、负责人、版本号等内容，并指定专人负责更新需求。第五，跟踪每项需求的状态：可以把每一项需求的状态属性保存在数据库中——状态如已推荐的、已通过的、已实施的、已验证的，这样可以在任何时候得到每个状态类的需求数量。

答案就是代码重构——它是开发活动，跟需求跟踪没关系。需求跟踪的活动围绕变更流程、影响分析、基准版本、历史记录、状态跟踪这五件事，练习题干里给的需求来源跟踪、需求状态跟踪、需求变更跟踪都是正牌活动。这句判断记牢：需求跟踪管需求，不管代码怎么写。

本集必背：文档是数据媒体和其中记录的数据，具有永久性；七大作用——管理依据、任务之间联系的凭证、质量保证、培训与参考、软件维护支持、历史档案、销售可能；三类文档——开发文档、管理文档、产品文档，按用途还可分内部文档和外部文档；质量五特征——针对性、精确性、清晰性、完整性、灵活性，没有「随意性」。需求变更控制三依据——项目计划、变更请求、绩效报告；理念「需求变更是必然的、可控的、有益的」；小变更也走正规流程；需求跟踪五活动——变更控制过程、影响分析、基准版本、历史记录、状态跟踪。

下一集讲软件质量与评审——IEEE 的软件质量定义、质量计划保证控制三分法、评审的五大目标与基本准则，其中「评审产品而不是评审设计者」这句话就是练习题第 7 题的答案。