文档的价值：架构文档写给谁看？如何让文档成为团队的“活地图”
很多团队做嵌入式开发，上来就写代码。文档？那是最后补的东西。我见过太多项目，代码跑得挺好，但换个人接手，三个月都理不清头绪。
说白了，文档不是写给老板看的。也不是为了应付评审。文档是写给未来的你，和你的队友看的。
谁在读你的文档？
我习惯把读者分成四类。每类人关注的点完全不同。
| 读者角色 | 核心诉求 | 文档侧重点 |
|---|---|---|
| 新入职的工程师 | 快速上手，知道从哪改代码 | 模块划分、接口定义、启动流程 |
| 同项目的队友 | 对齐设计思路，避免冲突 | 架构决策、关键约束、数据流 |
| 评审专家/架构师 | 验证设计是否合理，有没有坑 | 分层结构、依赖关系、异常处理 |
| 未来的自己 | 半年后还能看懂当初为什么这么设计 | 决策背景、权衡过程、遗留问题 |
文档的“活地图”属性
什么是活地图？不是那种挂在墙上落灰的装饰画。而是你走到哪，它都能告诉你：你现在在哪，周围有什么，前面有没有断头路。
我参与过一个车载项目，代码量超过50万行。刚开始没有架构文档，全靠几个老员工口口相传。后来老员工走了，新来的同事改一个bug，能引出三个新bug。为什么？因为没人知道模块之间的依赖关系。
后来我们重建了文档体系。核心就三张图：
- 模块关系图 —— 谁调用了谁，数据怎么流动
- 状态迁移图 —— 系统有哪些状态，什么条件下切换
- 时序图 —— 关键场景下，模块之间的交互顺序
这三张图，就是团队的活地图。新人来了，先看地图，再碰代码。效率提升不止一倍。
架构文档应该长什么样？
不是写作文。也不是写论文。我总结了一个“三明治”结构：
- 顶层：一张图 + 一句话 —— 系统整体架构图，配上不超过50字的定位描述
- 中间层：关键决策记录 —— 为什么选这个方案？放弃了什么？有什么风险？
- 底层：接口与约束清单 —— 模块暴露了什么接口？有什么前置条件？
避坑指南： 我曾经见过一份文档，写了200页，把每个函数的参数都列了一遍。结果没人看。为什么？因为太细了，细到和代码没区别。架构文档要回答的是“为什么”，不是“是什么”。代码本身就是“是什么”的最好文档。
让文档“活”起来的关键
文档最怕什么？写完之后就没人管了。版本迭代三次，文档还停留在第一版。你想想看，这比没有文档更可怕——它会把人带偏。
我建议团队建立三个机制：
- 文档与代码同库 —— 架构文档放在代码仓库里，和代码一起评审、一起合并
- 变更即更新 —— 任何架构层面的改动，必须同步更新文档，否则不允许合入
- 定期“扫墓” —— 每个迭代结束，花半小时检查文档是否还准确
一张图说清楚：文档的价值链
下面这张图，是我自己总结的。它展示了文档如何从“写出来”变成“用起来”。
文档的“活”体现在哪里？
活地图不是一成不变的。它会随着项目进展，不断更新。但更新不是乱改。我总结了三个“活”的特征：
- 可追溯 —— 每个决策都有背景，每次修改都有记录。你打开文档，能看到它从v1.0到v2.3的演变过程
- 可执行 —— 文档里写的，代码里都能找到对应。不是空话，不是理想设计，而是真实落地的东西
- 可讨论 —— 文档是团队讨论的起点，不是终点。大家对着文档提意见、改方案，而不是各自脑补
别让文档成为负担
有人会说：写文档太花时间了。项目周期本来就紧，哪有空写这些？
嗯，这个问题我遇到过。说实话，我也曾经这么想。直到有一次，一个模块出了问题，我花了整整两天才理清楚数据流向。如果当时有一份清晰的架构图，十分钟就能定位问题。
从那以后，我坚持一个原则：写文档的时间，不会超过写代码时间的20%。如果超过了，说明文档写得太细了。如果低于5%，说明团队在裸奔。
你想想看，20%的时间投入，换来的是后续维护效率提升50%以上。这笔账，怎么算都划算。