# 18. 文档

如何写 ADR、diagram、runbook 和 system context,让文档帮你做决策——而不是一周就过期。

- **Author:** Fedor Chishchin
- **Level:** advanced
- **Reading time:** 约 25 分钟阅读
- **Published:** 2026-05-23
- **Source:** https://fedorthinks.com/zh/learn/software-architect-18-documentation

---

## 1. 核心观点

你记录的不止是结果——你记录的是 context:为什么选这个、否决了哪些备选,以及什么时候该回头重新审视这个决策。

### ADR 把一个决策钉在时间里

> 施工现场的一张照片不能取代图纸,但它确实能帮你弄明白:这堵墙当初为什么砌在了这里。

一份 Architecture Decision Record 通常装着 context、decision、consequences、alternatives 和 status。它不必很长。它的职责是保存当时的推理。

一年之后,团队可能想不起来当初为什么选 Postgres、为什么放弃了 Kafka、为什么保留了一个同步 API。ADR 让你不必在没有原始 context 的情况下,把同一场争论重新打一遍。

### 一张图必须回答一个问题

> 地铁图不画下水道——乘客不需要。一张好图会挑选它的细节层级。

C4 model 作为一组层级很有用:context、container、component、code。stakeholder 需要的是 context。团队需要的是 container 和重要的 component。事故响应需要的是 runtime 视图和依赖关系。

一张画着"整个系统"的巨型大图通常没什么用:它要么过期,要么没法读。

## 2. 例子与反例

好的文档住在改动旁边,而且有 owner。

### 例子:为队列选型写一份 ADR

> 在会议纪要里,决定本身很重要——但"为什么其他选项不合适"同样重要。

这份 ADR 记下:我们需要投递领域 event,要支持 replay、按 key 的 ordering,以及持久化存储。我们考虑过 RabbitMQ、managed Kafka 和数据库 outbox。我们为了吞吐量选了 managed Kafka——并接受了它的运维成本和 schema governance 负担。

这样一份文档,能帮未来的团队看清:这个决策什么时候依然成立,什么时候 context 已经变了。

### 反例:把 Confluence 当成坟场

> 一仓库的旧说明书看着挺唬人——直到你意识到,没人知道哪一份是当前有效的。

文档和代码住在两处,没有 owner,PR 上不更新,还塞满了三年前的截图。新人很快就学会无视它。

更少的文档、配上清晰的生命周期,效果更好:owner、last-reviewed 日期、从代码链接过去、架构变更时必须更新。

#### 自检

- 哪些决策值得一份 ADR?
- 新人第一天需要的是哪张图?
- on-call 需要哪些 runbook?
- 团队怎么知道一份 文档已经过期了?

下一模块:[Communication](./software-architect-19-communication)。