上个月组里有个同事离职，交接文档写了三页 Word，其中两页是目录和标题。人走了之后，他负责的那套 CI 部署流程出了个问题，我们三个人对着他留下的"文档"研究了一下午，最后是靠翻聊天记录才把流程拼出来。

那天晚上我在群里发了句话：以后每个项目必须写文档，写完我 review。底下没人说话，但我能感觉到屏幕那头的不情愿——运维写文档，这事儿在很多人眼里就是浪费时间。

我理解这种抵触。我刚入行那会儿也觉得写文档是形式主义，有那功夫不如多排查几个问题。后来被坑了几次才改过来。

第一次被坑是刚工作第二年。有个同事搭了一套日志采集，没写任何文档。半年后他调岗，日志突然不收了，我接手查了一个通宵。最后发现是采集端有个 cron 脚本，依赖一个他自己改过的 Python 环境变量，而那台机器重启之后环境变量丢了。这事儿要是有文档，十分钟就能定位。没有文档，我花了一夜。

第二次是去年。我们给客户做的容灾方案，演练的时候发现脚本有个参数写死了机房 A 的 IP，切到机房 B 直接报错。写脚本的人早忘了这茬，他自己都说不清当时为什么写死。最后我们翻 git 历史，看到三年前的提交记录才明白——当时是为了绕过某个网络策略临时加的，后来忘了改回去。三年前的临时方案，三年后炸了，中间没有任何人知道。

所以我现在对文档的要求就三条，不搞那些虚的：

第一，写"为什么"，不写"是什么"。命令怎么敲、按钮怎么点，网上教程一大把，不用你抄。但"当时为什么这么配"——为什么用 3306 而不是默认端口，为什么备份策略是每天凌晨两点而不是三点，这些决策背景不写下来，后人只能猜。

第二，文档跟着变更走。改完配置顺手改文档，别攒到月底。攒着攒着就忘了，忘了就等于没写。我现在给自己定的规矩是：改完任何生产配置，当天必须把文档对应段落更新掉，哪怕只改一行字。

第三，交接文档必须能"跑通"。人走了，接手的人照着文档能独立把服务部署起来，这份文档才算合格。做不到这条，交接不签字。

我知道有人会说：小团队，人都在，写什么文档。但人都会走的，记忆会丢的，只有写下来的东西不会。说句不好听的，运维这行最贵的就是"只有某某人知道"这六个字。哪天那个"某某人"请假了、离职了、失联了，你就知道文档有多值钱了。

我那个离职的同事，后来我把他负责的流程重新梳理了一遍，写了一份能跑通的文档，花了两天。早知道当初就逼他写，也不至于现在自己补课。

写文档这事儿，短期看是浪费时间，长期看是给自己省时间。我宁愿现在多花十分钟，也不想到时候花一个通宵。