把文档当作代码来写、审、测、发，不是工具迁移，而是把文档的失败模式与代码对齐，并用同一套工程机制去消除。本报告提出 8 条可证伪核心论断，回溯一手来源，并给出可执行的反模式清单与 90 天路线图。
@scene#2 深度研究 · 论点驱动 · 含一手证据分级只读这一页也能用。下列每条论断都可被反证；正文的每一章都是对某条论断的展开与举证。证据强度按 RCT > 大样本观察 > 自报/调查 > 单一案例 > 建模 分级，厂商自利调查一律降级标注。
Docs-as-Code 的核心不是"用 Markdown 写文档"，而是把文档与代码共享的四种失败模式——漂移、缺审、静默损坏、难发现——用同一套机制（VCS / PR / CI / 测试）消除。缺这一条，换工具只是换皮。
文档债没有"构建失败"这种自动信号，随人员离职而被永久化，且以"重复提问"这条长期被低估的现金流线持续产生成本（可数模型约 400 工程师小时/年）。
Docs-as-Code 解决"怎么写/审/发"（流程），Diataxis 解决"该写什么"（结构）。两者正交，必须叠加；只上工具不补结构，文档会变成"格式正确但读不懂"。
单一工具（Markdown+Git）不构成 Docs-as-Code。真正的分水岭是 CI 中四条可自动验证的属性（链接、风格、新鲜度、代码变更联动）；而"句子是否为真"永远无法被自动化，必须路由到审查/再生成。
文档与代码同仓（docs-in-code）是消除漂移最有力的机制，但只适用于 API/SDK/开发者文档。产品端用户文档、非工程团队需要独立仓或混合方案，否则 Docs-as-Code 会变成排他性门槛。
llms.txt 与机器可读文档让 Git 里的 Markdown 成为 LLM 的天然输入；专有格式 Wiki 难以被处理。这使 Docs-as-Code 在 AI 辅助写作/检索时代获得相对 WYSIWYG 的结构性优势。
"把文档当代码"的过度类比催生四类反模式：用分支硬套写作流、忽略非技术贡献者（People Problem）、把"可检查"误当"充分"、版本化过度。
厂商调查（Stripe 17.3h、GitHub 40–60% 贡献）证据弱（自利+自报）；可数输入的自有模型（datadef 400h）与反事实案例（GitLab/Google/GDS 转型）才是可证伪基础。引用时须显式区分建模值与实测值。
先立判别式，再谈历史与分野。否则"文档即代码"会沦为一个筐——什么用 Git 存文档的工具都被塞进去，而真正的工程收益被稀释。
一个文档工作流是否属于 Docs-as-Code，可用下面 5 条逐一核验。全部满足才算；只满足前两条（纯文本 + Git）只是"把文档放进 Git"，离 Docs-as-Code 还差三道门禁。
| # | 判据 | 含义 / 反例 |
|---|---|---|
| 1 | 版本控制（Git） | 每次改动有作者、时间戳、diff、可回滚。反例：Confluence 时间线只能恢复"整页"，无法对任意两点做行级 diff，也无法把文档版本绑定到产品 release tag。 |
| 2 | 纯文本标记 | Markdown / reStructuredText / AsciiDoc，diff 干净、可合并、跨平台渲染。反例：二进制 .docx、Google Doc、Figma 画板——不可 diff、不可 lint。 |
| 3 | PR 评审 | 改动经同行评审（技术准确性 + 编辑清晰度），可要求审批后才合并。反例：任意人随时改任意页、无质量门。 |
| 4 | CI 自动构建 | 推送即构建并部署；构建期捕获断链、缺失图片、风格违例。反例：手动"导出 PDF 上传"产生的现实与文档之间的滞后。 |
| 5 | 持续部署 | 合并到主干即自动发布，无独立"发布"步骤。反例：文档与代码分两个系统协调发布，必然错位。 |
来源：Write the Docs 社区 Docs-as-Code 定义（issue tracker / VCS / plain-text / code review / automated tests）；Anne Gentle《Docs Like Code》"Write. Review. Test. Merge. Build. Deploy. Repeat."（2017/2022）。单一权威方法论
| 概念 | 它在回答什么问题 | 与 Docs-as-Code 的关系 |
|---|---|---|
| Docs-as-Code | "怎么写、审、发？"（工作流） | 本体。核心是开发者工具链 + 流程。 |
| Docs-in-Code | "文档放哪？"（同仓 vs 独立仓） | Docs-as-Code 的一种强实现：文档与代码同仓同分支，原子化消除漂移。仅适用于开发者文档。 |
| Single-Sourcing | "一处写、多处出？"（架构） | 正交能力：一份源出 HTML/PDF/CHM。可与 Docs-as-Code 叠加，但 DITA/Flare 也能单源而不"as code"。 |
| DITA | "如何结构化、复用、按条件出？"（信息架构标准） | 与 Docs-as-Code 正交：DITA 是严格 XML 架构（topic/map/condref），Docs-as-Code 是轻量标记 + 流程。两者可共存（如 AsciiDoc + Antora）。 |
来源：Dr.Explain《Docs as Code vs DITA》(2026)；kacperbojakowski 标准实践笔记（single-sourcing / reuse / DITA）。单一案例 / 教学笔记
来源：Tom Johnson（I'd Rather Be Writing）趋势梳理；Write the Docs 官方 Docs-as-Code 页面（2015–2019 大会演讲清单）。历史/会议记录
Docs-as-Code 不是审美偏好，而是对"文档与代码共享失败模式"这一事实的工程回应。每条理论都应能推出一个具体动作。
文档与代码在四种失败模式上同构，因此同一套对策有效：
| 失败模式 | 代码侧的解法 | 文档侧的同构解法（Docs-as-Code） |
|---|---|---|
| 漂移（现实变了，产物没变） | 版本控制 + 自动测试 | 文档与代码同仓/同分支，改 API 的 PR 同时改文档，原子提交 |
| 缺审（错误没人抓） | 代码评审 | PR 评审：技术准确性由写代码的人审，写作质量由审文档的人审 |
| 静默损坏（坏了自己不报错） | CI 测试 / 依赖扫描 | CI 跑断链检查、风格 lint、代码样例执行；坏链/坏样例让构建失败 |
| 难发现（找不到该看的） | 部署流水线把应用送到用户面前 | CI 把 Markdown 构建成可搜索、可导航站点并自动部署 |
来源：unmarkdown《Docs-as-Code in 2026》(哲学章节)；Anne Gentle《Docs Like Code》。方法论
"Everything-as-Code" 谱系把所有会随时间变化、需要历史、需要一致性的配置都收进版本化文本：基础设施（IaC）、策略（Policy-as-Code）、流水线（Pipeline-as-Code）、监控、以及文档。仓库成为"系统应当如何"的唯一事实源；偏离可被识别与纠正。
当文档是代码，它若变得不准确，就会让测试失败。—— Everything-as-Code 谱系的核心推论
来源：techblueprints《Everything as Code》；ai-solutions.wiki《Treating All Artifacts as Software》(IaC 史：Puppet/Chef 2005 → Terraform 2014 → 泛化)。综述/观察
把类比推到尽头会出错。三处硬边界：
来源：tianpan.co 论坛 eng_director_luis 一线实践；docsio《Docs as Code vs WYSIWYG》(贡献者广度维度)；GitLab 文档测试页（editorial review 难自动化）。一线/调查
Docs-as-Code 的主循环是 Write → Review → Test → Merge → Build → Deploy → Repeat。每个环节都对应一个可被 CI 验证的属性（见第 06 章），这正是它区别于"写完即发"的关键。
| 环节 | 谁做 | CI 中可验证的属性 |
|---|---|---|
| ① 编写 | 开发者 / 技术写作者 | —（生成源） |
| ② 评审 | 同行（技术 + 编辑） | 要求审批；linked PR 触发文档评审 |
| ③ 测试 | CI | 断链、风格、code-doc 联动、样例可执行 |
| ④ 合并 | 维护者 | 分支保护规则 |
| ⑤ 构建 | CI | 构建零错误（strict/nitpicky 模式） |
| ⑥ 部署 | CI | 自动发布到 staging/prod |
来源：Write the Docs 文档测试指南（CI 跑 build/link/style）；GitLab 文档测试页（各环节 CI 任务）。工程实践
Docs-as-Code 不是某款产品，而是一组可组合的工具。选型由"谁写、读者是谁、要不要多版本、是否多仓聚合"四个问题驱动。
| 工具 | 标记/栈 | 强项 | 典型场景 | 代价 |
|---|---|---|---|---|
| Sphinx | reST / Python | 跨引用强、nitpicky 严格构建、科学计算生态 | Python 库、科研 | rST 学习曲线 |
| MkDocs | Markdown | 极简、默认主题干净、配置直接 | 中小型 API/SDK 文档 | 多版本/交互弱 |
| Docusaurus | MDX / React | 版本化 + i18n + 博客 + 插件生态（5万+ star） | 大型站点、需交互组件 | 构建复杂、React 依赖 |
| Antora | AsciiDoc | 多仓聚合 + 组件化多版本（分支=版本） | 多产品/分布式团队 | AsciiDoc + playbook 概念门槛 |
| Hugo | Go / Markdown | 极快构建、模板丰富 | 大体积站点 | Go 经验要求（GDS 教训） |
| Astro Starlight | Island / 框架无关 | 默认零 JS、内置搜索、增长最快 | 2026 新建站点首选 | 生态较新 |
来源：unmarkdown《Docs-as-Code in 2026》(工具栈四层)；startup-house《Modern technical documentation tools》(Sphinx/MkDocs/Docusaurus 取舍)；ivanwalsh(Antora 用例)；GDS 选 Middleman 弃 Hugo 的教训。综述 / 案例
来源：docsio《Docs as Code vs WYSIWYG》(贡献者广度维度)；Doctave(同仓文化)；Typemill(混合团队)。调查/实践
Docs-as-Code 解决"流程"，但流程正确不等于内容正确。Diataxis（Daniele Procida）是必须叠加的结构模型：把技术文档切成四种互不混淆的类型。混写是"格式正确但读不懂"的根因。
Diataxis 的最大价值在预防：教程中途插参考细节 → 两头不讨好；操作指南开头讲原理 → 赶时间的读者流失。一家银行用 Diataxis 重构 DevSecOps 能力文档后，自助解决率 measurable 上升，Slack 里"怎么…"类问题显著下降。
来源：Daniele Procida Diátaxis（diataxis.fr，CC-BY-SA）；dwaynehelena 银行落地案例。方法论 / 单一案例
单一工具不构成 Docs-as-Code。分水岭是 CI 中能自动验证的四条属性。GitLab 把这些做成了 MR 必过的 job：docs-lint markdown（Vale + markdownlint）、docs-lint links、docs-lint mermaid、以及监听代码路径的联动规则。
来源：GitLab 文档测试页（Vale/markdownlint/link/mermaid/redirects 等 CI job）；datadef《Documentation checks in CI》(四类检查 + 诚实边界)；Write the Docs 测试指南（link/style/ build）。工程实践
证据强度分化严重。厂商自利调查给出诱人大数但不可证伪；可数输入的自有模型和反事实案例才是地基。本节显式分级。
datadef 用一个"所有输入都可在自己团队里数出来"的模型估算文档债年化成本。在中等规模团队输入下，三条线合计约 400 工程师小时/年，且主导线不是多数人猜的入职或事故，而是重复提问——因为它每周复利，而前两者是偶发的。
来源：datadef.io《Cost of outdated documentation》(建模，输入可替换)；同站《docs-checks-in-ci》。建模（输入可证伪）
落地 Docs-as-Code 有前期下沉（工具搭建、Git/CI 培训、文化阻力），越过回本点后净收益陡升。谷底由"工具 + 培训 + 文化"三因叠加，这正是很多团队在 month 1–3 放弃的位置。
| 数据 | 数值 | 来源 / 年份 | 证据强度 | 备注 |
|---|---|---|---|---|
| 开发者处理技术债/坏代码 | 17.3 h/周 | Stripe Developer Coefficient 2023 | 自报/厂商 | 自利调查，数值偏激励性 |
| 强文档项目外部贡献 | +40–60% | GitHub Octoverse（大样本） | 大样本观察 | vendor survey，相关性非因果 |
| 每天 >30min 搜索答案 | 61% | Stack Overflow Dev Survey 2024 (65k) | 大样本观察 | 开发者自报占比 |
| 每周损失 >8h 低效 | 69% | Atlassian State of DevEx 2024 (2100+) | 大样本观察 | 文档不足被点名 |
| 团队不跟踪任何文档指标 | 39% | State of Docs 2025/2026 | 自报/调查 | 多数只测 page view |
| 文档维护者中技术写作者占比 | 35% | State of Docs 2026 | 自报/调查 | 其余 65% 为非工程角色 |
| 文档债年化成本（中等团队） | ~400 eng-h | datadef 可数模型 | 建模 | 输入可替换、可证伪 |
| AI 生成代码 churn 率 | +41% | GitClear 2024 | 大样本观察 | 类比：AI 文档也需人审 |
| Word→as-code 发布时延 | -25%→-50% | AWS 某团队（案例） | 单一案例 | 弱，无对照 |
| 开发者入职周期 | 2–4 周 | Red Hat 迁移（案例） | 单一案例 | 弱 |
| API 文档改进后工单 | -30% / 6月 | Twilio（案例） | 单一案例 | 弱，厂商 |
不度量就不知道债务在哪。State of Docs 2025 显示 39% 团队不跟踪任何文档指标，多数只测 page view——这恰好是会被 Goodhart 定律劫持的代理。
| 层 | 指标 | 为什么 |
|---|---|---|
| 领先（可干预） | doc-shaped 提问数、PR 中 doc 联动率、last_reviewed 过期页数 | 在成本发生前预警；本周就能数 |
| 滞后（结果） | 入职周期、文档相关工单、外部贡献数 | 验证投入是否回本 |
| 健康度（最难） | 文档准确率抽样通过率（审计：内容是否仍反映现实） | 唯一逼近"真值"的指标，需人工 |
来源：promptless.ai《What Documentation Debt Actually Costs》(39% 不跟踪指标；审计映射)；datadef（领先指标=提问数）。调查 / 建模
选型、CI 配置、SSG 搭建。一次性投入，别过度。
先迁 top-10 高频页 + Diataxis 重排，尽快出可见收益。
"文档进 DoD"硬约束 + 非技术贡献者的低门槛入口。
来源：路线图综合 GitLab/Google/GDS 转型节奏与 datadef 门禁实践；投资配比为本研究基于案例的相对建议。综合实践
| 层 | 反模式（症状） | 修正 |
|---|---|---|
| 战略 | 全员强推 as-code：非技术贡献者流失、文档停滞 | 按读者切分；产品端用 WYSIWYG / 混合方案（论断 5） |
| 战略 | 工具优先于内容：3 周配 Docusaurus 却零迁移 | 先迁移 top-10 高频页，工具够用即可 |
| 工程 | 把"可检查"当"充分"：lint 全过即以为正确 | 加新鲜度门禁 + 真值抽样审查（论断 4/7） |
| 工程 | 分支硬套写作流：写文档也开 feature 分支 → 冲突、反馈慢 | 短命分支 + 草稿预览（staging） |
| 工程 | 版本化过度：每个小改都开版本分支，维护爆炸 | 仅对受支持 release 多版本 |
| 治理 | 无 owner：文档无人更新、随人离职消失 | 每 docs 绑定命名 owner / 团队 |
| 治理 | 口号式 DoD：说"文档进完成定义"却无 CI 强制 | CI 强制：watched 路径 PR 不带 doc 改动即拦截/warn |
| 治理 | 指标用 page view：以为热门=准确 | 改用领先指标（提问数、联动率、过期页） |
这是观点，不是共识。 下方判断基于前述证据，但 Docs-as-Code 社区内部对"是否该全员强推""Diataxis 是否必需"仍有分歧。
一句话判断： Docs-as-Code 最该被用于开发者文档 / API / SDK / 内部运行手册这类"文档随代码变、作者会 Git"的场景；它是消除文档债最便宜的工程杠杆。但它不是文档的终极形态，对产品端用户文档与非工程团队，WYSIWYG 或混合方案更优。
落地的关键不是工具，而是三件事：① 把校验贴在改动发生的那一刻（PR/CI）；② 叠加 Diataxis 结构，否则"格式正确但读不懂"；③ 用文档进 DoD 的硬约束越过 J 曲线谷底——文化阻力是绝大多数失败的真实原因，不是技术。
八条核心论断回看：论断 1（失败模式对齐）是本体；论断 2（文档债更隐蔽）解释了为何值得做；论断 3（流程×结构正交）给出做法；论断 4（四条可验证属性）给出分水岭与诚实边界；论断 5/6（同仓双刃、AI 结构性优势）给出适用边界与未来；论断 7（强类比是最大反模式）、论断 8（证据分级）给出避坑与可信度纪律。
证据分级说明：本报告对厂商自利调查（Stripe/AWS/Twilio）与单一案例一律降级标注，以可数输入的 datadef 模型与反事实转型案例为可证伪地基。所有数值回溯一手来源或注明为建模值。