第三章 需求文档的编写规范
写需求文档这事儿，我做了十几年硬件，见过太多坑了。有人觉得写文档就是走形式，有人恨不得把每个引脚都画出来。其实都不对。
今天我就把压箱底的经验掏出来。需求文档怎么写，才能让开发、测试、项目经理都看得懂、用得上。
3.1 需求文档的结构：别让读者猜
我刚开始带项目时，写过一份“自由发挥”的需求文档。结果呢？硬件工程师说看不懂功能描述，测试说找不到验收标准，项目经理直接拍桌子了。
从那以后，我给自己定了个规矩：需求文档的结构必须固定。就像盖房子要有图纸，写文档也得有模板。
我个人习惯用这样的结构：
- 文档概述：项目背景、目标、范围、术语定义
- 功能需求：按模块划分，每个模块独立描述
- 非功能需求：性能、功耗、可靠性、EMC等
- 接口需求：电气接口、通信协议、机械接口
- 约束条件：成本、时间、技术路线、合规要求
- 验收标准：怎么才算“做完了”
- 附录：参考文档、变更记录
我的小技巧：每个章节前面加一段“本章导读”，用两三句话告诉读者这章讲什么、重点在哪。别小看这个，能省下不少沟通成本。
3.2 需求描述的五要素：一个都不能少
你想想看，一个需求如果只说“系统要能通信”，那跟没说一样。到底用什么协议？波特率多少？数据格式是什么？
我总结了一个五要素模型，每次写需求都拿它来检查：
| 要素 | 含义 | 示例 |
|---|---|---|
| 角色 | 谁在使用这个功能 | 现场工程师、上位机软件 |
| 功能 | 要做什么事 | 读取传感器温度值 |
| 输入 | 需要什么条件或数据 | I2C地址0x48，读取命令0x00 |
| 输出 | 产生什么结果 | 返回16位温度值，单位0.1℃ |
| 约束 | 有什么限制条件 | 响应时间≤10ms，功耗≤5mW |
举个例子。我曾经接手过一个项目，需求文档里写着“系统支持OTA升级”。结果开发做了个通过蓝牙升级的版本，客户要的是通过4G网络升级。为什么？因为没写清楚输入和约束。
用五要素重新描述：
- 角色：远程运维人员
- 功能：通过4G网络远程升级固件
- 输入：固件文件（.bin格式，最大2MB），设备ID
- 输出：升级成功/失败状态，升级进度百分比
- 约束：升级过程中不能断电，失败后自动回滚到上一版本
你看，这么写，谁都不会理解错。
避坑指南：我曾经见过一个需求，输出写的是“显示正常”。什么叫正常？不同人理解完全不一样。输出一定要可量化、可验证。比如“LED绿灯常亮”就比“显示正常”好得多。
3.3 需求编号规则：给每个需求一个身份证
项目做到一半，测试说“需求3.2.1有问题”。你翻遍文档，发现3.2.1是个章节编号，根本不是需求。这种混乱我经历过太多次了。
所以，我强烈建议给每个需求一个唯一编号。编号规则要简单、可扩展、一看就懂。
我常用的格式是：
[项目代号]-[模块缩写]-[需求类型]-[序号]举个例子：
- PJ001-PWR-FUNC-001：项目001，电源模块，功能需求，第1条
- PJ001-COMM-PERF-002：项目001，通信模块，性能需求，第2条
- PJ001-MCU-CONS-003：项目001，主控模块，约束条件，第3条
需求类型我一般用这几个缩写：
| 缩写 | 含义 |
|---|---|
| FUNC | 功能需求 |
| PERF | 性能需求 |
| INTF | 接口需求 |
| CONS | 约束条件 |
| SAFE | 安全需求 |
| TEST | 测试需求 |
重要提醒：编号一旦分配，就不能修改或删除。如果需求变更，可以标记为“废弃”或“替代”，但编号要保留。这样做的好处是，所有历史记录都可追溯。我见过有人删了编号重新排，结果测试用例和需求对不上，查了三天才找到原因。
3.4 写需求文档的几个实战技巧
嗯，这里再分享几个我踩过的坑：
- 用主动语态：“系统应检测温度超过阈值时报警”，而不是“温度超过阈值时报警应被系统执行”。后者读起来太绕了。
- 避免模糊词：“大约”、“可能”、“尽量”这些词在需求文档里就是毒药。我见过一个需求写“功耗尽量低”，结果硬件做了3W，软件说1W就够了，吵了一个星期。
- 每个需求都要可测试：写完之后问自己一句“这个需求怎么测？”如果答不上来，说明写得太虚了。
- 版本控制：需求文档一定要有版本号和变更记录。我习惯用“V1.0”、“V1.1”这样的格式，每次变更都要注明日期、变更人、变更内容。
说白了，需求文档不是写给领导看的，是写给干活的人看的。你写得越清楚，后面返工就越少。这个道理，我做了十年硬件才真正明白。
下一章我会讲怎么把需求拆解成可执行的任务。到时候见。