别人能操作的运行手册

运行手册是决定一个部署能不能活得比它的作者更久的文件。多数手册是在最后写的，由要走的人凭记忆写，描述的是当初设计的系统，而不是正在跑的那个。修法是第二周就写——那时意外还是新鲜的——然后拿一个不在场的人来测。

九个部分

1. 三句话说清这是什么。 它做什么、谁在用、它停了他们的工作会怎样。架构放到后面再说。

2. 正常路径。 从触发到产出的一条编号序列，每一步写真实的命令或界面。哪一步有两个可能，其中一个是异常路径，放进第 5 部分。

3. 东西都在哪。 账号、仓库、看板、客户那边的系统名、密钥库。要写具体账号，不写「团队的账号」——共享登录等于没人负责的风险。

4. 要盯的数字和正常范围。 三到五个指标，每个都带一个「正常」的区间。没有期望值的看板，教不会任何人什么叫异常。

5. 失败模式，和每一种的第一个动作。 真正出过问题的五到十件事，带发现信号和第一步处置。这一部分是这份文件存在的理由，其余都只是导览。

6. 怎么关掉它。 具体步骤、测过、写明耗时、写明谁能授权。也要写怎么打开——没人练过的回滚只是一种希望。

7. 数据：存在哪、留多久、怎么删。 任何碰到个人数据的部署都必需，而且在审计里被要求的频率比团队预期的高得多。

8. 已知的技术债。 大家都知道脆的那三处、为什么留着、什么情况下才修。技术债清单是空的手册，没人会信。

9. 打给谁，为什么打。 具体的人，加上升级阈值，与升级路径对齐。

证明它能用的测试

把第 2、5、6 部分交给一个从没碰过这个系统的人，给他一个真任务：带一条记录走完正常路径、诊断一个你埋的故障、把功能关掉再打开。全程闭嘴看着他做。

三种结果。他做完了，文件是真的。他卡在一个假设了常识的步骤上，你修那一步。他来问你问题——把那个问题记下来，它就是缺口。

在交接会之前跑这个测试，不要在会中跑。会在中才被测的手册，等于在依赖它的人面前现场改稿。

手册的几种失败

写来好看的。 架构图、设计理由、一段关于为什么选 Kafka 的说明。凌晨两点的人一样都用不上，而它们把真正要操作的内容挤到了后面。

照着设计写，不是照着系统写。 手册里写三个服务，生产上跑四个，第四个是第六周为了修超时加的。凡是没对着正在运行的系统核过的，都是虚构。

交接后没有归属人。 没有维护者的文件，从写完那天就开始腐化。顶上写一个名字、一个复核日期就够了；这一行把一份文件变成一项承诺。

口头补丁。 「有事你可以随时找我。」这是最常见、也最有害的一种失败，因为它意味着交接没发生——FDE 去了下一个客户，实际上仍然是这个系统的运维，而且不拿这份钱。

它在撤离里的位置

运行手册是日落条款所说的交接的主要交付物，它的第 5 部分来自它所描述的那个部署的事故复盘。第二周就写手册的部署，交接一天；最后一周才写的，交接一个月，而且还在漏。

动笔前该问的那一句

到底是谁会打开这份文件，打开的时候他正在做什么？如果答案是一个有名字、有岗位的人，就为他写，把其余全删掉。如果没有这样一个人，那才是真正的发现：这个部署在客户侧没有负责人，没有任何文档能修好它。这就是干系人地图里点名的那个缺口。