文档债：过期文档比没有更难处理
文档债的典型形态不是文档缺失，而是文档与代码不一致：照着文档操作会失败，误导新人与排障。原因是文档被放在独立位置，与实际变更脱节。治理方向是让文档贴近代码——就近的说明文件、关键实现处的注释、架构决策记录，并把关键文档的更新纳入变更检查清单，改接口时同步改文档。
症状与治理
| 症状 | 搭建指南过时、接口文档与实现不符、参数说明缺失 |
|---|---|
| 治理 | 文档就近存放，变更时同步更新，定期核对 |
| 度量 | 刚入职者按文档走一遍的失败次数 |
| 配套 | 变更检查清单中列出需要同步的文档项 |
典型使用场景
- 新人上手：按搭建文档实际走一遍，把失败点作为待修清单
- 接口变更：同步更新对外文档与示例，避免调用方按旧说明接入
- 配置新增：更新部署说明与参数表，减少反复询问
- 故障处理：把排障步骤沉淀为可执行的处置手册
- 架构决策：记录决策背景与取舍，避免后续重复讨论
变更同步清单
变更同步清单
# 提交前逐项确认
- 接口变更 → 更新接口文档与调用示例
- 配置新增 → 更新部署说明与参数表
- 流程调整 → 更新处置手册
- 架构决策 → 补决策记录，并在原文档留引用文档位置对照
| 文档类型 | 建议位置 | 更新时机 |
|---|---|---|
| 项目搭建说明 | 仓库根目录说明文件 | 依赖或步骤变化时 |
| 模块设计说明 | 模块目录内就近存放 | 结构或职责调整时 |
| 接口说明 | 与接口定义同处维护，尽量自动生成 | 接口签名变化时 |
| 处置手册 | 运维仓库，按服务组织 | 故障复盘产生新步骤时 |
| 决策记录 | 仓库内的决策目录 | 重要取舍确定时 |
能自动生成的文档优先自动生成：接口说明从定义生成、参数表从配置生成，可以减少人为遗漏。人工维护的部分聚焦在决策背景与操作步骤上。
文档集中放在独立仓库时更新惰性更大：改动代码的提交往往不会同时改另一处文档，漂移会持续累积。尽量把必要的说明放在被修改代码附近。
落地检查清单
- 关键文档的位置便于随代码一起更新
- 变更检查清单包含文档同步项
- 有人按文档走一遍并记录失败点
- 定期清理明显过期的文档，避免误导