大多数文档项目在同一个环节上失败。它是在团队会真正使用它的前提下搭建的，却从未被真正需要答案的那一刻验证过。这就是为什么最好的文档不是目录最漂亮的那份，而是周四下午四点被打开、被编辑、被相信的那份。
过去三年我在多支分布式团队观察到，真正决定文档寿命差异的几乎总是机制，而不是写作质量。写作能力强但没有评审循环的团队，一个季度就会失去文档价值。写作能力一般但评审循环严格的团队，能用同一份文档跑很多年。
Forrester 2024 年的知识管理研究指出，把文档评审接入代码评审循环的团队，文档存活率最高能到单独写作冲刺团队的两倍。机制很简单：文档在它描述的对象变化时被打磨，而不是靠某个人想起去更新它。
第一步：用决策树给每份文档分类
在选工具之前，先用两条轴给每份文档分类：变更频率与阅读对象。
| 变更频率 | 受众窄、面向工程 | 受众广、跨职能 |
|---|---|---|
| 每周或以上 | Docs as code。Runbook、部署说明、功能文档 | Docs as code，配一个镜像 Wiki 视图 |
| 每月 | Docs as code，评审更轻 | Notion 或 Confluence 之类的 Wiki |
| 每季度或更慢 | Wiki。设计文档、路线图、复盘 | Wiki。制度、入职、价值观 |
团队最容易判断错的两个格子是右上角和左下角。每周变更、受众又广的文档，通常是架构决策与 API 契约。因为牵涉的人多，它们必须走版本控制。每季度才变更、受众又窄的文档，往往是内部设计规格。它们既不需要 Wiki，也不一定要代码评审。
分类时问三个问题：底层系统多久变一次；读者是谁；文档错了的代价有多大。三个答案中任何一个偏高，这份文档就必须放进版本化的流程里。
第二步：按文档类型选工具，而不是按公司
最常见的错误是把文档当成一次公司级决策。它其实是一份一份的决策。
| 维度 | Docs as Code（GitLab、GitHub、Docusaurus） | Notion（或 Confluence） |
|---|---|---|
| 评审模式 | PR 驱动，与代码评审绑定 | 评论驱动，零散 |
| 最佳场景 | Runbook、API 文档、功能文档 | 手册、入职、复盘 |
| 变更频率 | 每周及以上 | 每月及以下 |
| 发现方式 | 仓库内搜索与交叉链接 | Wiki 搜索与页面层级 |
| 负责人 | 工程 code owner | 职能负责人，通常轮值 |
| 单次编辑成本 | 高，需走 PR 流程 | 低，拖拽即可 |
| 无治理下的漂移风险 | 高 | 更高，编辑发生在视线之外 |
| 版本历史 | 完整 Git 历史，可 blame | 有版本历史，追溯较难 |
| 贡献者学习成本 | 中等，需要 Git 素养 | 低，非工程角色上手即用 |
| 典型团队适配 | 分布式工程密集团队 | 分布式团队且非工程角色较多 |
当「文档错了」的代价高时，选 docs-as-code。凌晨三点值班工程师接手自己没写过的代码时执行的 runbook，需要评审痕迹和 blame 指针。当「编辑慢」的代价高时，选 Notion。一份被五十位非工程同事使用的手册需要在决策当下就能被更新，而不是等一次 PR 评审循环结束。
多数分布式团队最后都是两套都用。关键在于把边界画清楚，并且捍卫它。一份同时存在于两处的文档，两边都不是它的事实源。
第三步：搭出第一个贡献循环
工具不是工作流。工作流是每当有人改动文档所描述的系统时都会被触发的那个循环。
一个最小的贡献循环包含四件事：
- 带「文档必填」勾选项的 PR 模板
- 会让构建失败的断链 CI 检查
- 把每条文档路径指派给一位负责人的 CODEOWNERS 文件
- 评审轮值，避免单点瓶颈
模板做了大多数工作。如果 PR 模板强迫作者回答「是否改动文档」，大约一半的漂移会立刻消失。剩下的另一半靠 CI 检查和 CODEOWNERS 文件。
下面是一份处理了大部分工作流的 PR 模板：
yaml
name: "Docs PR"
body:
- type: textarea
id: summary
attributes:
label: "What changed"
description: "One sentence describing what this PR changes."
validations:
required: true
- type: checkboxes
id: docs-required
attributes:
label: "Docs"
options:
- label: "Docs updated or added in this PR"
required: true
- label: "Docs verified as still accurate (no changes needed)"
- label: "N/A. This change does not affect docs"
- type: checkboxes
id: review
attributes:
label: "Review"
options:
- label: "Link check passed"
required: true
- label: "CODEOWNERS owner assigned as reviewer"
required: true真正重要的勾选项是第三个：N/A。它强迫作者明确写出「本次变更不影响文档」。沉默是文档的敌人。PR 模板里的沉默尤其刺耳。
第四步：执行三阶段落地
整个落地过程分三阶段，横跨四到六周。跳过阶段一直接冲工具，你总有一天会在他人的混乱目录里发现 docs-as-code 与 Wiki 的边界到底画在哪里。
| 阶段 | 周期 | 主要范围 | 成功标准 |
|---|---|---|---|
| 阶段一：决策 | 第一二周 | 决策树、试点范围、负责人指派 | 每类文档已分类。选定一个试点区。负责人到位。 |
| 阶段二：搭建 | 第三四周 | 模板、CI、首个贡献循环 | 首个基于模板的 PR 已合入。断链检查通过。负责人响应评审。 |
| 阶段三：扩展 | 第五六周 | 评审轮值、复盘、归档清理 | 复盘成文。归档清单达成一致。轮值日历发布。 |
阶段一是团队最常跳过的阶段。别跳。这两个周的决策比后面一个月的编辑更有价值。
阶段一里只选一个试点区。它应当是当下最痛的那类文档。常见选择包括入职手册、部署 runbook 或 API 参考。不要试图一次性迁移全部，你会在循环被验证之前就把精力耗光。
阶段二是大多数团队最关注的阶段。把模板放进去，接上 CI 检查，让第一份真正的贡献通过新流程落地。成功标准不是 pipeline 在 hello-world 上变绿，而是一位真实工程师按新流程做出了一次真实改动。
阶段三决定工作流能否长久。引入评审轮值；跑一次复盘并写下来；把最近六十天没人打开过的文档归档。归档不是可选项。没有它，阶段三就会退化回团队想离开的数字地下室。
案例：一家 FinTech 的入职迁移
我在一家拥有约十九位工程师、跨五个时区的小型金融科技公司跑过这套流程。他们的入职耗时六周，团队希望把它压到三周。
阶段一用了九个工作日。团队在两个小时的会话中画出决策树，给四十二份现有文档分类，选定入职手册作为试点区，并指派三位负责人：一位管工程入职，一位管安全入职，一位管业务入职。
阶段二用了十个工作日。入职手册被移到 docs-as-code 专用目录，配了 PR 模板、CODEOWNERS 条目与断链 CI 检查。第一周团队迁移了五份入职内容。第八个工作日，一位新工程师更新了一份环境搭建脚本文档，评审自动指派到位，第一次完整的贡献循环就此跑通。
阶段三用了八个工作日。轮值日历发布；首次复盘暴露出三个摩擦点，两个当场修复，第三个成为后续 ticket；团队把九十天无人打开的四份文档归档。
下一位入职的工程师用了大约三周走完 onboarding。这不是一个神奇数字。团队能持续用这套流程，靠的是机制立得住，而不是谁承诺了什么。
失败模式：让工作流夭折的三件事
几乎所有团队栽在同样的三个坑里。
- 文档脱离代码评审循环。 一旦文档与它描述的变更分离，漂移就会开始。先配 PR 模板，再写 CODEOWNERS，最后再选工具。
- 单一负责人扛下整个工作流。 负责人变成瓶颈，评审堆积，没人再提交文档改动。轮值要在阶段三引入，而不是阶段五。
- 归档清单从未被触碰。 文档越堆越多，搜索结果变嘈杂，最后谁也不信任任何一份。阶段三做归档，之后每季度重复一次。
这三件事都是治理选择，不是工具选择。工具本身修不了它们。
第一天我会做的三件事
如果你的团队已经有文档但没跑起来，在动任何工具之前做三件事：画出决策树；选定一个试点区；接好 PR 模板。工作流没定下来之前，不要买新 Wiki。工具由工作流决定，反过来不行。
按三阶段跑通并坚持使用真实 PR 模板的团队，工作流会一直持续。跳过阶段直接冲工具的团队，接下来半年都在清理自己刚刚搭出来的烂摊子。
最好的文档不是「如果你有完美一个季度你会写的那份」。最好的文档是别人在周五下午也能改的那份。