# 《软件文档写作教程》知识点全解

> AI生成｜2026年10月28日｜codebuddy｜原书：马平 黄冬梅编著《软件文档写作教程》，电子工业出版社，2010-04-01
> **我的阅读**：进度 99%｜累计 6小时27分钟｜开始 2022-08-19｜最近 2023-05-10｜读完 2023-04-19

**一句话总结**：它回答"软件项目里那些必须写却常写成废话的文档，该写什么、给谁看、写到什么颗粒度"，把立项、投标、需求、设计、验收、总结这条生命线逐段拆成有骨架、可评审、可追责的文本。

**适合谁**：项目经理、需求与系统分析人员、乙方售前与实施人员，以及要写课程设计、毕业设计报告的计算机专业学生。甲方负责人也该读——知道文档该长什么样，才不会被糊弄。

**不适合谁**：想学 Markdown、API 文档、Docs-as-Code 的读者。本书成书于 2010 年，重心是工程管理类文档而非开发者文档，工具与协作方式已明显过时。

**前置知识**：最好经历过一个完整项目（哪怕课程项目），知道需求、设计、测试、验收各自在做什么；否则"内容要点"会退化成背条目。不需要编程能力。

## 一、全书地图

微信读书未返回可用目录，以下按文档在生命周期中的位置分块，不代表原书章节顺序。

| 阶段 | 文档 | 回答的问题 | 主要读者 |
|---|---|---|---|
| 机会识别 | 项目建议书 | 为什么值得投这笔钱 | 决策层、投资方 |
| 立项论证 | 可行性研究报告 | 能不能做、划不划算、风险可控吗 | 立项评审组 |
| 项目获取 | 投标文件 | 能否满足要求、凭什么选我 | 评标委员会 |
| 需求确认 | 需求分析书 | 为谁做什么、做到什么程度 | 用户、开发、测试 |
| 方案设计 | 概要设计书 | 怎么分层分块、模块怎么接 | 架构评审、开发 |
| 实现依据 | 详细设计书 | 每个模块内部怎么实现 | 编码人员 |
| 交付确认 | 项目验收报告 | 是否逐项达成、证据是什么 | 甲方、监理、审计 |
| 复盘沉淀 | 项目总结报告 | 什么可复用、什么要写进组织记忆 | 管理层、后续项目 |

主线是一条**承诺链**：建议书提出承诺 → 可研验证 → 投标报价 → 需求译成条目 → 设计译成方案 → 验收核销 → 总结评估兑现质量。文档靠引用与编号咬合，一环脱节，后面就是各写各的。另有两条贯穿线：**文档管理**（模板、编号、版本、归档）与**文档评审**。

## 二、核心知识点

**1. 文档是交付物，不是副产品**

是什么：文档与代码同属交付物，有版本、有责任人、可被验收，纳入配置管理。

为什么重要：软件的价值在可维护，而接手的人能读到的只有文档；文档缺失，项目在交付那刻就开始贬值。

怎么用：立项时把文档写进 WBS 与里程碑，与代码同步评审归档，而非结项前集中补写。

常见误区：把文档当交差材料，验收前一周批量生产——这种文档只有封面是真的。

**2. 一份文档只服务一类主读者**

是什么：动笔前锁定主读者（决策者/使用者/实现者/审计者），据此定详略、术语密度与结论位置。

为什么重要：决策者要结论与风险，实现者要参数与约束，塞进一本必然两头不讨好。

怎么用：先写一句读者画像：他是谁、读完要做什么决定。正文只留支撑该决定的内容，细节进附录。

常见误区：以为"写得全"等于"写得好"，把决策文档写成技术手册。

**3. 立项双件：建议书谈必要，可研谈可行**

是什么：项目建议书讲背景、必要性、目标、初步范围与投入产出，争取立项资格；可行性研究报告从技术、经济、操作、进度、合规五维论证，给方案比较与结论。

为什么重要：这是止损点。多数失败项目不是做不好，而是本不该做。

怎么用：每维给判据而非形容词——技术看有无成熟方案与团队经验，经济算全周期成本含运维；结论必须写"可行/不可行/有条件可行"并附前提。

常见误区：写成"技术先进、意义重大"的颂歌；只算建设成本；只给一个方案，没有比较就没有论证。

**4. 投标文件赢在响应性**

是什么：对招标文件逐条应答的技术、商务、报价组合，核心是证明"每一条要求我都接住了"。

为什么重要：评标多为符合性审查加打分，漏答一条实质性条款即可能废标。

怎么用：做"要求—应答—证据"三列对照表，逐条标满足/部分满足/不满足；偏离项单列偏离表并给替代方案；方案按评分点顺序排，方便评委找分。

常见误区：套旧标书不改项目名；只写优势不写偏离；方案炫技却与评分标准无关。

**5. 需求分析书：把"用户说的"变成"可验证的"**

是什么：写清功能需求、非功能需求（性能、安全、可用性、兼容性）与设计约束，每条编号、可测、无二义，并能双向追溯到设计与测试。

为什么重要：需求是设计、开发、测试、验收的共同基准；需求含糊，等于把争议留到验收。

怎么用：一条好需求含"谁、在什么条件下、做什么、得到什么可观测结果"，如"断网时店员仍可收银，联网后 5 分钟内自动上传交易"；用追踪矩阵把 FR-012 这类编号接到模块与用例。

常见误区：把界面草图当需求；只写功能不写非功能（性能与安全正是扯皮高发区）；编号中途改版，矩阵沦为摆设。

**6. 概要设计书：定全局决策，不定实现细节**

是什么：给出架构、分层与模块划分、模块职责与接口、数据模型、技术选型、部署与异常视图。

为什么重要：这是返工代价最大的一层；概要错了，详细设计写得再漂亮也白费。

怎么用：每个模块写"职责—接口—依赖—数据"四件事；用架构图、模块图、E-R 图承载结构，文字只解释取舍理由。

常见误区：概要里塞满代码级细节；只画框图不写接口契约；不记录"为什么不选另一个方案"。

**7. 详细设计书：写到照着能写代码**

是什么：模块内部的算法、数据结构、处理流程、界面元素、错误处理与边界条件。

为什么重要：它是编码与单元测试的直接依据，也是交接时最省时间的文档。

怎么用：按模块给"输入—处理—输出—异常"四段；复杂算法配流程图或伪代码；界面元素标明状态与校验规则。

常见误区：把源码贴进文档当设计（代码会变，文档不会跟着变）；只写正常路径。

**8. 项目验收报告：用证据逐项闭环**

是什么：对照合同、需求与验收标准，逐项列交付内容、完成情况、测试结论与遗留问题，形成可签字的结论。

为什么重要：它是收款与责任划分的依据；写法决定遗留问题是"已确认的后续工作"还是"未完成的违约"。

怎么用：列验收项清单，每项附证据（测试报告编号、截图、签字单）；未达成项写明原因、责任方、补救计划与时间；结论明确"通过/有条件通过/不通过"。

常见误区：只写成绩不写遗留；证据只有一句"经测试运行正常"；拿验收会纪要代替验收报告。

**9. 项目总结报告：把项目变成组织资产**

是什么：复盘目标达成度、进度与成本偏差、质量数据、经验教训、可复用组件与方法建议。

为什么重要：不总结，同样的坑会在下个项目重演；这是组织唯一能"记住"的机制。

怎么用：用数据说话（计划与实际工期、缺陷密度、变更次数），教训写到"下次遇到同类情况该怎么做"的程度，而非"沟通不够"。

常见误区：写成表彰材料；教训不敢指向流程；只总结技术不总结管理与客户关系。

**10. 文档语言：单义、可测、少形容词**

是什么：以陈述句与主动语态为主，一个术语只对应一个概念，能量化的一律给数字与单位。

为什么重要：读者是执行者，二义性会直接变成实现分歧与验收争议。

怎么用：建术语表全文统一；把"较快""尽量""适当"换成阈值；长句拆成一事一句；用"必须/应/可"区分强制程度。

常见误区：用文学化表达渲染气氛；中英混称同一对象；把"应该"当"必须"，责任边界模糊。

**11. 模板是下限，裁剪与版本要留痕**

是什么：模板保证不漏项、便于评审；裁剪按项目规模与合同要求删减章节并说明理由；受控文档打基线、留修订记录。

为什么重要：小项目套大模板写出一半空话，大项目用简版会漏掉关键约束；无版本则必然出现"以哪份为准"的争执。

怎么用：先定必备项（范围、需求、接口、验收标准）与可选项，裁剪处注明"本章节依约定不适用"；封面放版本号、日期、作者与变更摘要。

常见误区：整章删掉且不说明；把模板空格全填满以显得完整；改完不升版本号。

## 三、关键概念速查表

| 概念 | 一句话解释 | 用在哪儿 |
|---|---|---|
| 可行性研究 | 从技术、经济、操作、进度、合规论证该不该做 | 立项决策前 |
| 响应性 | 投标文件对招标要求的逐条接住程度 | 符合性审查 |
| 偏离表 | 集中列出与招标要求不一致处及替代方案 | 投标、合同谈判 |
| 功能/非功能需求 | 前者是行为，后者是性能、安全等质量约束 | 需求书、验收标准 |
| 需求追踪矩阵 | 需求与设计、代码、测试、验收的双向映射 | 变更影响、验收举证 |
| 接口契约 | 模块对外提供的输入、输出与前置条件 | 概要设计 |
| 验收标准 | 判定"做完了"的可观测条件 | 合同附件、验收报告 |
| 基线 | 经评审确认、后续变更须走流程的版本 | 配置管理 |

## 四、可复用的方法/框架

**读者—目的—证据三问**：读者是谁 → 读完要做什么决定 → 支撑该决定最少需要哪几条证据。答不出就先别动笔。

**承诺链检查法**：建议书 → 可研 → 投标 → 需求 → 设计 → 测试 → 验收，逐环问"上一步哪一条由我这一步哪一条接住"，接不住的就是缺口。

**需求条目模板**：`[ID] 当<角色>在<条件>下，需要<能力>，以便<目的>；验收以<可观测指标>判定。`

**评审五查**：完整性、与上游及术语表的一致性、可测性、编号可追踪性、结论是否前置。评审只记录问题，不现场改写。

**裁剪三问**：合同是否要求 → 缺失会不会引发验收争议 → 维护方是否需要；三者皆否才可删，并留痕。

## 五、我的阅读轨迹

| 项目 | 数据 |
|---|---|
| 进度 | 99% |
| 累计阅读 | 6小时27分钟 |
| 开始阅读 | 2022-08-19 |
| 最近阅读 | 2023-05-10 |
| 读完时间 | 2023-04-19 |

99% 与"已读完"并存，说明当时很可能跳读了收尾部分（验收与总结易被视为重复）；6.5 小时通读、无笔记，属于"过了一遍"，留存率不会高。

复习建议：不必从头重读，优先回看**需求分析书**（条目化与可测性）、**概要与详细设计的分界**（最易写混）、**验收报告的证据组织**（决定回款），这三块占实操价值七成。可研与投标属场景触发型，接到任务再查。

## 六、行动清单

1. 拿手上一个真实项目，按承诺链画七环，标出断在哪一环。
2. 挑一份旧需求文档，用条目模板重写 10 条，删掉所有不可测形容词。
3. 建本项目术语表，统一三个以上混用词（如用户/客户/账号）。
4. 给现有文档补一张追踪矩阵，先做核心 20 条需求的闭环。
5. 用评审五查评一份同事的设计文档，只记录问题不改写。
6. 为团队模板做一次裁剪，写明必备项、可选项与裁剪理由。
7. 找一份真实招标文件，做一页"要求—应答—证据"对照表。

## 七、延伸阅读

1. **《软件工程：实践者的研究方法》（Roger Pressman）**——先读或并行读。本书每类文档都嵌在软件过程里，先有过程全局观，才知道文档为何在此出现。
2. **《需求工程：基础、原理和技术》（Klaus Pohl）**——接在本书需求章节之后。本书给骨架，这本补获取、建模、协商与管理的完整方法。
3. **《金字塔原理》（芭芭拉·明托）**——随时可读。本书解决"写什么"，它解决"怎么让结论先被看见"，对可研、建议书、总结的说服力提升最直接。

> 说明：本书成书较早，模板与国标引用请以现行 GB/T 8567《计算机软件文档编制规范》及本组织体系文件为准，具体条款对应关系待核对。