技术文档最佳实践:架构决策记录(ADR)、运维手册、故障复盘报告怎么写

文档不是写给别人的，是写给三个月后的自己。

“这代码当时为什么这么设计？”

“这个配置是干什么用的？”

“上次那个故障怎么解决的来着？”

这些问题，你是不是每天都在问？答案往往散落在聊天记录里、某个人的脑子里、或者更糟——根本没人知道。

技术债务不只有代码，还有文档。

今天，我想聊聊技术文档的三种核心类型：架构决策记录（ADR）、运维手册、故障复盘报告。不是为了写文档而写文档，而是为了“三个月后自己和团队还能看懂”。

一、架构决策记录(ADR)：记录“为什么”，而不是“是什么”

1.1 ADR 是什么？

ADR 记录一次重要的架构决策，重点不是“我们做了什么”，而是“为什么这样做”。

一份好的 ADR 能让新成员快速理解历史决策的上下文，避免“推翻重来”的冲动。

1.2 一份标准 ADR 的模板

1.3 存放位置

/docs/adrs/ADR-001-状态管理选型.md，用编号 + 简短描述命名，方便检索。

二、运维手册：让“页面挂了”不再恐慌

2.1 运维手册的核心目标

运维手册要回答的核心问题是：“系统出问题时，第一步做什么？”

它不要求覆盖所有场景，但要覆盖最常见的 5-10 种故障场景，并给出明确的排查步骤。

2.2 一份标准运维手册的模板

2.3 存放位置与更新频率

推荐放在 Confluence/语雀/Notion 等可协作的平台上，方便多人维护。每次系统变更后同步更新，至少每半年做一次完整 review，确保电话、人员信息不过期。

三、故障复盘报告：从“道歉”到“改进”

3.1 复盘不是追责

很多团队的故障复盘变成了“追责大会”——谁写的 bug、谁合并的代码、谁没发现。这恰恰是复盘的反面。

好的复盘报告只回答两个问题：

• 发生了什么？（事实，不掺水分）

• 我们怎么避免它再发生？（改进，而非追责）

3.2 一份标准复盘报告的模板

3.3 复盘的三个原则

• 原则 1：不对人，只对事

• 原则 2：5 Whys 分析法——连续问 5 个“为什么”，直到找到根因

• 原则 3：改进措施必须可验证（有负责人、有 deadline、有验收标准）

四、三种文档的协作模式

最后

技术文档不是为了“好看”，而是为了“好用”。

1. ADR 让你三个月后还能记得“为什么这么设计”

2. 运维手册 让你半夜被叫醒时知道“第一步做什么”

3. 复盘报告 让同一个坑不再踩第二次

从今天开始，选一个你刚做的技术决策，写一份 ADR。不用太长，三五百字就行。三个月后你会感谢现在的自己。

如果这篇文章对你有帮助，欢迎点赞、在看、转发。