文档债是什么
文档债指系统与流程已经变化、文档却没有同步的差额，来源通常是四类：变更不同步、缺少模板、没有责任人、经验只靠口头传承。它的代价不是「文档不好看」，而是上手变慢、有人照着过期步骤误操作、故障时无据可依。治理手段有三个抓手：把文档更新写进完成定义（Definition of Done）、在变更评审里核对受影响文档、定期做文档与现状的对账；大扫除式重写通常撑不过一个迭代周期就再次过期。
基本信息
| 来源 | 变更不同步、缺模板、无责任人、口头传承 |
|---|---|
| 代价 | 上手变慢、误操作、故障时无据可依 |
| 治理 | 完成定义含文档 + 变更检查 + 定期对账 |
| 优先级 | 按「被搜索次数 × 失效概率」排序补写 |
| 利息 | 越晚补，重新核实现状的工作量越大 |
典型使用场景
- 新人上手周期变长，反复追问同几个基础问题
- 变更上线后运维按旧手册操作，出现偏差
- 事故复盘发现处置步骤与现网不一致
- 审计或认证要求提供与现状一致的文档证据
- 知识库条目数增长但可用性下降，需要识别失效内容
完成定义示例
完成定义示例
☑ 代码合并 # 变更本身完成
☑ 测试通过 # 功能验证完成
☑ 变更说明更新 # 对外沟通材料同步
☑ 受影响的 Runbook 已更新 # 操作手册与现网一致
☑ 监控与告警同步调整 # 可观测性随变更一起交付
☑ 台账与架构图同步（如有影响） # 资产与结构记录不留缺口债务来源与治理
| 来源 | 常见表现 | 治理动作 |
|---|---|---|
| 变更不同步 | 上线新版本后文档仍写旧路径 | 把文档更新列入完成定义并纳入评审 |
| 缺模板 | 每篇格式随意，关键信息时有时无 | 建立模板库，必填字段附示例 |
| 无责任人 | 读者反馈无人响应，内容逐年腐化 | 标注 owner 与复审日期，交接时移交 |
| 口头传承 | 只有少数人知道操作与坑点 | 把口述内容落到清单式步骤并验证 |
| 过期未下架 | 历史方案与现行方案并存 | 归档旧版并标注替代关系 |
补文档要按优先级而不是按顺序：优先处理被搜索最多、又最可能失效的条目（生产操作、故障处置、权限申请），这类内容一旦过期，代价会直接出现在线上。