2. 验收文档体系：文档类型、生命周期与模板

说到验收文档，很多工程师第一反应就是「写文档好烦」。我理解这种心情。但做了十几年项目，我越来越觉得——文档不是写给甲方看的，是写给自己和团队看的。

一个项目能不能顺利验收，文档体系占了六成功劳。剩下的四成，才是你的技术实现。今天我就把这套体系掰开揉碎了讲给你听。

2.1 文档类型：四大金刚

信号系统项目里，文档就四种类型。不多不少，刚刚好。我管它们叫「四大金刚」。

文档类型	核心作用	谁写	谁看
需求文档	说清楚「要做什么」	系统工程师	甲方、开发、测试
设计文档	说清楚「怎么做」	硬件/软件工程师	开发、评审专家
测试文档	证明「做对了」	测试工程师	质量部、甲方
部署文档	告诉别人「怎么用」	运维/实施工程师	现场人员、客户

需求文档，说白了就是合同的技术翻译。甲方说「我要一个能测心跳的盒子」，你得把它翻译成「采样率不低于250Hz，ADC精度12位，信噪比大于60dB」。我在项目中遇到过最坑的事，就是需求文档里写了个「实时显示」，结果甲方验收时要求延迟小于1ms。嗯，从那以后，所有模糊词我都要求甲方签字确认。

设计文档，这是工程师的命根子。你想想看，一个信号处理板卡，滤波器阶数、截止频率、窗函数类型，这些不写清楚，三个月后你自己都看不懂。我习惯在设计文档里加一个「设计决策记录」小节，专门记录为什么选A方案不选B方案。这招救过我很多次。

测试文档，这是验收的硬通货。测试用例、测试数据、测试结果，缺一不可。我曾经见过一个项目，测试文档写了200页，但全是「通过」「通过」「通过」。评审专家问了一句：「你们测过极限情况吗？」全场沉默。所以测试文档里，一定要有边界条件和异常场景。

部署文档，这个最容易被忽视。很多工程师觉得「装个软件谁不会啊」。但现实是，现场实施人员可能连IP地址都不会配。部署文档要细到什么程度？我举个例子：每一步操作都要配截图，每个配置文件都要给模板，每个异常情况都要给解决方案。

2.2 文档生命周期：从生到死

文档不是写完了就完事了。它有自己的生命周期。我把它分成五个阶段。

1. 起草阶段：项目启动时，先搭框架。别追求完美，先把目录写出来，把关键点列出来。我习惯用思维导图先画一遍，再转成文档。
2. 评审阶段：文档写完后，必须评审。评审不是走过场。我要求评审专家必须在文档上签字，签了字就代表他认可了。这招能逼着评审专家认真看。
3. 定稿阶段：评审通过后，文档进入受控状态。受控的意思是——不能随便改。要改可以，走变更流程。我在项目中遇到过最头疼的事，就是有人偷偷改了设计文档，结果测试那边不知道，按老版本测，全测错了。
4. 维护阶段：项目执行过程中，文档要跟着更新。但注意，不是所有修改都要更新文档。只有影响接口、功能、性能的变更，才需要更新。我一般定一个规则：每周五下午统一更新一次文档。
5. 归档阶段：项目验收后，文档归档。归档不是扔进文件夹就完事了。要建立索引，要标注版本号，要写清楚归档日期。我见过最惨的案例：项目验收三年后，客户要升级系统，结果找不到原始设计文档。最后只能重新逆向工程，花了双倍的钱。

2.3 文档模板：拿来就能用

模板这东西，我建议不要自己从头造。直接用行业标准模板，然后根据项目特点微调。下面是我常用的几个模板框架。

需求文档模板

1. 项目背景与目标
2. 功能需求（编号、描述、优先级、验收标准）
3. 性能需求（指标、单位、条件、容差）
4. 接口需求（电气接口、通信协议、数据格式）
5. 环境需求（温度、湿度、振动、EMC）
6. 约束条件（成本、进度、法规）
7. 术语表
8. 附录（参考文档、会议纪要）

注意，需求文档里的每一条都要有编号。比如「REQ-FUNC-001」。这样测试文档里可以直接引用。我习惯用Excel管理需求，然后导入到文档里。这样改起来方便。

设计文档模板

1. 系统架构图
2. 模块划分与功能描述
3. 关键算法设计（公式、流程图、伪代码）
4. 硬件设计（原理图、PCB布局、器件选型）
5. 软件设计（状态机、任务调度、内存管理）
6. 接口设计（信号定义、时序图、协议帧格式）
7. 设计决策记录（方案对比、选型理由、风险分析）
8. 附录（仿真结果、计算书、参考设计）

设计文档里，我最看重的是「设计决策记录」。为什么？因为三个月后你回头看，你会问自己「我当时为什么这么设计」。有了这个记录，你就能快速回忆起来。我曾经靠这个记录，在评审会上怼回了一个不合理的修改要求。

测试文档模板

1. 测试环境（设备清单、软件版本、连接图）
2. 测试用例（编号、名称、前置条件、测试步骤、预期结果）
3. 测试数据（输入信号、参数设置、数据文件）
4. 测试结果（通过/失败、实际值、偏差分析）
5. 缺陷记录（编号、描述、严重等级、状态）
6. 测试结论（是否通过、遗留问题、建议）

测试文档的模板，我建议每个测试用例都包含「预期结果」和「实际结果」两列。这样评审专家一眼就能看出问题。另外，测试数据要可复现。我习惯把测试数据打包成ZIP文件，和测试文档一起归档。

部署文档模板

1. 系统概述（硬件配置、软件版本、网络拓扑）
2. 安装步骤（前置条件、安装流程、验证方法）
3. 配置说明（参数列表、配置文件模板、修改方法）
4. 操作指南（开机、关机、日常操作、异常处理）
5. 维护手册（定期检查、故障排查、备件清单）
6. 附录（安装日志、配置备份、联系方式）

部署文档，我要求写得像「傻瓜教程」。每一步都要有截图，每个命令都要有示例输出。为什么？因为现场实施人员可能不是原班人马。你写清楚一点，能省掉无数个求助电话。

2.4 文档质量检查清单

文档写完了，怎么判断质量？我总结了一个检查清单。每一条都打勾，打不满就别提交。

• 完整性：四种文档都齐了吗？有没有遗漏的章节？
• 一致性：需求、设计、测试、部署之间，有没有矛盾的地方？
• 可追溯性：需求编号能在测试用例里找到吗？设计决策有记录吗？
• 可读性：语言通顺吗？图表清晰吗？术语有定义吗？
• 版本控制：文档有版本号吗？变更记录写了吗？
• 签字确认：该签字的人都签了吗？

这个清单我打印出来贴在工位上。每次提交文档前，自己先过一遍。说实话，能全部打勾的文档不多。但至少，你知道哪里还有坑。

好了，文档体系这部分就讲到这里。下一章我们聊聊具体的文档编写技巧——怎么把技术文档写得既专业又易懂。嗯，那才是真正的功夫。