2. 文档体系设计：嵌入式软件文档的分类
做嵌入式开发这么多年，我见过太多项目栽在文档混乱上。有的团队需求写在一张草稿纸上，有的把接口文档藏在某个人的硬盘里。说白了，文档体系没搭好，项目越大越容易翻车。
这一章，我就聊聊嵌入式软件文档到底该怎么分类。我个人习惯把文档分成五大类：需求、设计、接口、测试、部署。这五类基本覆盖了一个嵌入式产品从想法到交付的全过程。
核心观点：文档分类不是为了应付流程，而是为了让信息在正确的时间、以正确的方式、传递给正确的人。
2.1 为什么需要文档分类？
你想想看，一个嵌入式项目少说也有几十个模块。没有分类，文档就像一堆散落的零件。找需求要去翻设计文档，找接口定义要去问老员工——这种场景我见过太多次了。
分类的好处其实就三点：
- 可追溯：需求变更了，能快速定位到受影响的设计和测试用例
- 可复用：接口文档独立出来，新模块可以直接调用，不用重新造轮子
- 可交接：新人来了，按分类看文档，一周就能上手。我曾经接手过一个项目，光找启动流程就花了三天——就是因为文档全混在一起
2.2 五大文档分类详解
下面这张图是我自己总结的文档体系结构。每次做新项目，我都会先画出这个框架，再往里面填内容。
2.3 需求文档
需求文档是所有文档的源头。没有它，后面的设计、测试全是空中楼阁。我在项目中遇到过最典型的问题就是：需求写得太模糊，开发做完了才发现跟客户要的根本不是一回事。
嵌入式需求文档通常包含这几块：
| 需求类型 | 内容说明 | 示例 |
|---|---|---|
| 功能需求 | 系统必须实现的具体功能 | 系统上电后 3 秒内完成自检 |
| 性能需求 | 响应时间、吞吐量、精度等指标 | ADC 采样率 ≥ 1kHz |
| 约束条件 | 硬件资源、成本、功耗等限制 | RAM 使用 ≤ 64KB |
| 接口需求 | 与外部系统的交互方式 | 支持 CAN 2.0B 协议 |
我的习惯：需求文档里每条需求都要有唯一编号。比如 REQ-FUNC-001。这样后面设计文档和测试用例引用起来特别方便。我曾经吃过一次亏，需求没编号，结果变更时根本不知道改哪里。
2.4 设计文档
设计文档是把需求翻译成技术方案的地方。我一般把它拆成两层：
- 架构设计文档：描述系统整体结构、模块划分、任务调度、内存布局。读者是全体开发人员
- 详细设计文档：描述每个模块的内部实现，包括数据结构、算法、状态机。读者是模块负责人
举个例子，一个智能家居网关的架构设计文档会画出模块图，说明 Wi-Fi 模块、Zigbee 模块、本地控制模块之间怎么通信。而详细设计文档则会写清楚 Zigbee 模块的入网流程、数据帧格式、错误处理逻辑。
注意：设计文档不要写成代码注释的堆砌。我见过有人把整个 .c 文件贴进去，那叫代码打印，不叫设计文档。设计文档要回答「为什么这么设计」，而不是「代码长什么样」。
2.5 接口文档
接口文档是嵌入式项目里最容易出问题的环节。为什么？因为接口涉及多方协作——硬件工程师、嵌入式软件工程师、上位机工程师、测试工程师。任何一方理解偏差，都会导致联调失败。
接口文档应该独立成册，包含：
- API 函数接口：函数名、参数、返回值、调用说明
- 数据结构定义：结构体、枚举、宏定义
- 通信协议：帧格式、命令码、校验方式、超时重传机制
- 硬件接口：引脚定义、电平标准、时序要求
我记得有一次做车载项目，CAN 报文的 ID 分配在接口文档里写错了，结果硬件和软件各按各的理解做，联调时发现报文全对不上。后来我们定了个规矩：接口文档必须由双方签字确认才能生效。
2.6 测试文档
测试文档不是测试用例的简单罗列。它应该形成一个完整的质量保障体系：
| 测试阶段 | 文档名称 | 主要内容 |
|---|---|---|
| 单元测试 | 单元测试报告 | 每个函数的测试用例、覆盖率、通过率 |
| 集成测试 | 集成测试方案 | 模块间接口测试、数据流测试、异常场景 |
| 系统测试 | 系统测试报告 | 功能验证、性能测试、压力测试、稳定性测试 |
| 验收测试 | 验收测试记录 | 对照需求文档逐条验证，客户签字确认 |
关键点：测试文档要能追溯到需求。每条测试用例都应该标注它覆盖了哪条需求编号。这样需求变更时，能快速知道哪些测试用例需要更新。
2.7 部署文档
部署文档是嵌入式项目里最容易被忽视的。很多团队觉得「烧录进去就行了」，结果到了现场才发现烧录步骤写错了、配置文件版本不对。
部署文档应该包含：
- 烧录指南：烧录工具、烧录步骤、常见错误处理
- 配置说明：配置文件格式、参数含义、默认值
- 运维手册：日志查看、故障诊断、固件升级流程
- 环境要求：硬件版本、依赖库版本、操作系统版本
我曾经在项目交付前夜发现部署文档里写错了烧录地址，差点导致现场几十台设备全部变砖。从那以后，我要求部署文档必须经过实际环境验证，不能光靠「我觉得」。
2.8 文档之间的关联关系
这五类文档不是孤立的。它们之间有一条清晰的链条：
- 需求文档定义「做什么」
- 设计文档定义「怎么做」
- 接口文档定义「怎么连」
- 测试文档验证「做对了没」
- 部署文档告诉用户「怎么用」
我建议用编号体系把这条链串起来。比如：
- 需求编号：REQ-FUNC-001
- 设计编号：DES-MOD-001（对应 REQ-FUNC-001）
- 测试编号：TST-FUNC-001（对应 REQ-FUNC-001）
这样，任何一个环节变更，都能快速定位到上下游文档。嗯，这个习惯帮我省了不少加班时间。
2.9 文档分类的裁剪原则
不是所有项目都需要五类文档全上。小项目可以合并，大项目可以拆分。我一般按这个原则来：
| 项目规模 | 建议文档 | 说明 |
|---|---|---|
| 单人小项目（< 3个月） | 需求 + 接口 + 部署 | 设计和测试可以合并到代码注释和自测记录里 |
| 团队中型项目（3-12个月） | 五类全上，适当精简 | 设计文档可以只写架构设计，详细设计用代码注释代替 |
| 大型项目（> 12个月） | 五类全上，严格评审 | 每类文档都要有版本管理和变更记录 |
我的建议：刚开始做文档体系时，别追求一步到位。先搭个框架，把核心文档写出来，后面再慢慢补充。文档是活的，不是一次写完就完事了。