7.8 软件文档
软件产品不只是代码。课程里特别强调：代码和文档结合起来，才构成最终交付的软件产品。文档的作用是沟通、评审、交接、维护和管理；没有文档的软件，后期维护会变成成本很高的猜谜。
文档按阅读者分类
本节考试不要求掌握每一种文档的细枝末节，重点是能按阅读者区分：产品/用户文档、管理文档、开发文档。
| 分类 | 主要阅读者 | 作用 | 典型文档 |
|---|---|---|---|
| 产品文档/用户文档 | 最终用户、运维或支持人员 | 帮助安装、学习、使用和获得支持 | 产品手册、用户指南、参考手册、操作手册、支持手册 |
| 管理文档 | 项目经理、管理人员、评审人员 | 支持计划、控制、职责划分和变更记录 | 项目计划、进度报告、职责定义、变更记录、评审记录 |
| 开发文档 | 分析、设计、开发、测试、维护人员 | 支持系统开发、测试和后期维护 | 可行性研究报告、项目任务书、需求规格说明书、设计说明书、测试计划、质量保证计划 |
题目常给一组文档名称，让你判断属于哪类。关键词“用户如何使用”多半是产品/用户文档；“进度、职责、变更、绩效”多半是管理文档；“需求、设计、测试、质量计划”多半是开发文档。
软件文档为什么重要
文档的价值在于降低信息损耗。开发团队里，需求来自用户，设计来自架构人员，代码由开发人员实现，测试人员依据规格验证，维护人员可能几年后才接手。如果这些知识只存在某个人脑子里，人员一流动，系统就很难继续演进。
mermaid
flowchart LR
U["用户需求"] --> R["需求规格说明书"]
R --> D["设计说明书"]
D --> C["编码实现"]
R --> T["测试计划/测试用例"]
D --> T
C --> M["维护与升级"]
R --> A["验收依据"]
T --> REG["回归测试依据"]需求文档支撑设计和验收，设计文档支撑编码和维护，测试文档支撑验证和回归。文档不是额外负担，而是跨阶段协作的接口。
文档的编写时机
课程里讲到一个常见误区：测试相关文档不一定只能在测试阶段编写。V 模型的思想提醒我们，测试计划和测试用例可以在需求、设计阶段就开始准备。
| 文档 | 合理阶段 | 说明 |
|---|---|---|
| 需求规格说明书 | 需求分析阶段 | 是设计、测试和验收的重要依据 |
| 概要/详细设计说明书 | 系统设计阶段 | 指导编码、接口协作和维护 |
| 测试计划、测试用例 | 可从需求/设计阶段开始 | 不必等到编码后才设计 |
| 用户手册 | 可随功能逐步编写，交付前完善 | 面向最终用户使用 |
| 变更记录 | 变更发生时持续记录 | 支持追溯和项目管理 |
如果题干说“测试设计必须在测试阶段编写”，这是过于绝对的说法。
文档质量原则
虽然考试主要考分类，但真实学习要知道什么文档才有用。
| 原则 | 含义 | 反例 |
|---|---|---|
| 准确 | 与实际需求、设计、代码一致 | 代码已改，接口文档仍是旧字段 |
| 完整 | 覆盖必要范围和约束 | 只写正常流程，不写异常处理 |
| 清晰 | 读者能理解，不靠口头补充 | 大量缩写和口头约定 |
| 一致 | 前后术语、编号、接口含义一致 | 同一字段在不同文档中含义不同 |
| 可追溯 | 能从需求追到设计、代码和测试 | 缺陷无法定位影响范围 |
| 可维护 | 文档能随软件变更更新 | 文档一交付就没人维护 |
文档质量差会直接降低可维护性。一个系统“代码能跑但没人敢改”，常常不是代码单独造成的，而是文档、测试和版本历史一起缺失。
三类文档的边界
| 题干描述 | 应归类 |
|---|---|
| “说明用户如何安装、操作、查询和获取支持” | 产品/用户文档 |
| “定义团队职责、记录进度变更、控制项目开发过程” | 管理文档 |
| “描述需求、功能规格、概要设计、测试计划和质量计划” | 开发文档 |
| “最终用户阅读，帮助使用软件” | 产品/用户文档 |
| “开发人员阅读，帮助实现和维护软件” | 开发文档 |
注意：同一个词在不同教材里可能叫“用户文档”或“产品文档”。软考题干更重要的是阅读者和用途。
例题
面向最终用户，说明如何使用系统的文档是：
关于文档编写阶段，下列说法不正确的是：
本节小结
软件文档与代码共同构成软件产品。考试重点是按阅读者分类：产品/用户文档面向用户，管理文档服务项目控制，开发文档服务分析、设计、编码、测试和维护。另一个易错点是测试文档可以提前编写，不必等到测试阶段。