写在文档里的配置，迟早会和现实脱节。文档是快照，而系统是活的——两者之间的时间差，就是 bug 的温床。
我曾经维护过一份很详尽的服务文档：端口、路径、依赖、启动顺序，全写得很清楚。结果某天真的需要重建环境时，发现文档里有三处和实际情况不一致，其中一处直接导致服务起不来。
问题出在「写」这个动作本身
写文档的时候，人会不自觉地按记忆和理解来写，而不是照抄当前状态。于是文档记录的是「它应该是这样」，而不是「它现在是这样」。
更可靠的做法
我现在尽量让配置自己成为唯一事实来源，具体有三个做法：
- 配置从运行中的系统导出，而不是凭印象重写一份。导出脚本和导出结果一起进版本库。
- 文档只写「为什么」和「怎么操作」，不重复写「是什么」。「是什么」让系统自己回答。
- 把校验做成自动的：每次部署后跑一遍检查，把实际状态和声明的状态对比，对不上就让流水线失败。
关于冗余
你会发现第三点做完之后，文档里的大段配置描述就可以删掉了。这不是偷懒，是把「记录」这件事从人身上移到了机器身上——机器不会记错，也不会忘记更新。
文档最重要的职责不是描述现状，而是解释为什么是这样。
当然，完全不写文档也不行。自动导出能告诉你「现在是什么」，但只有人能解释「为什么当初选了这个方案、什么时候该换」。前者交给机器，后者留给自己。