| 症状 | 搭建指南过时、接口文档与实现不符 |
|---|---|
| 治理 | 就近文档 + 变更时同步 + 定期核对 |
| 度量 | 刚入职者按文档走一遍的失败次数 |
变更同步清单
变更同步清单
□ 接口变更 → 更新 API 文档与示例
□ 配置新增 → 更新部署说明
□ 流程调整 → 更新 runbook
□ 架构决策 → 补 ADR 并在原文档留链文档债：过期文档比没有文档更危险
文档债的典型是「文档与代码不一致」：误导新人与排障；治理方式是文档贴近代码（就近 README、代码注释、ADR），把关键文档纳入变更检查清单（改接口同步改文档）。
易错点
- 文档集中在独立仓库：更新惰性大，漂移更快
- 为文档而文档：缺少读者与场景的文档迅速过期
数据来源与参考
- 文档债治理实践（docs-as-code 与就近文档）综合