从问题开始，而不是从 Git 开始
Docs-as-Code 常被描述成一组工具：Markdown、Git、pull request、CI 和静态站点生成器。团队因此很容易先争论编辑器，却没有先回答：现有文档流程到底哪里出了问题？ 常见问题包括内容过期、评审缓慢、术语不一致、链接失效，或者发布完全依赖某一个人。
只有当 Docs-as-Code 能明显降低这些摩擦时，它才有价值。
Docs-as-Code 实际包含哪些环节
| 环节 | 发生什么 | 简单方案 | 更成熟方案 |
|---|---|---|---|
| 源文件 | 修改内容 | Git 中的 Markdown/AsciiDoc | 结构化内容 + metadata schema |
| 编辑 | 作者写作 | GitHub 网页编辑器 | github.dev、VS Code、IDE 或 authoring UI |
| 预览 | 查看未来页面 | 本地/网页 build | 每次 change 都有 preview |
| 自动检查 | 机器发现例行问题 | links + build | style、术语、API、accessibility、locales |
| 评审 | 验证含义 | 单一 reviewer | SME + 编辑评审 |
| 发布 | 更新站点 | 手工 | checks 通过后 CI/CD |
目标不是把每一行都做到最复杂，而是选择足够解决实际风险的最小方案。
文本格式不等于必须使用 IDE
GitHub 可以直接在浏览器中编辑文件。github.dev 也在浏览器中运行，并提供仓库搜索、语法高亮和 source control，无需本地 clone。偶尔修改一次术语的 SME 没有必要学习 terminal 和 rebase。
| 参与者 | 通常足够 | 不应无理由强制 |
|---|---|---|
| Technical writer | github.dev、VS Code 或习惯的编辑器 |
指定某一种 IDE |
| 偶尔参与的 SME | 网页编辑 + preview | terminal、rebase、本地 build |
| Developer | IDE + Git | 如果 Markdown 更方便则无需额外 CMS |
| Editor | 浏览器/authoring UI | pipeline 内部细节 |
存储格式和作者使用的界面是两件不同的事。
一个合理的端到端流程
产品变化 → 草稿 → preview → 自动检查 → 技术评审 → 编辑评审 → merge → 发布 → production 检查。
小团队可以由一人承担多个角色，pull request 不必成为仪式。大团队中，SME 应确认事实，technical writer 负责用户任务、结构、术语和清晰度。
哪些检查值得自动化
| 检查 | 能发现什么 | 好的错误信息 |
|---|---|---|
| Build | syntax、include、template | 文件 + 明确原因 |
| 内部链接 | 删除的页面/anchor | 来源 + 目标 |
| Metadata | title、owner、locale、revision | 错误字段 |
| Heading structure | 层级问题 | 具体 heading |
| Terminology | 过期术语 | 术语 + 推荐替换 |
| Style lint | 编辑规则 | 简短可执行说明 |
| Code example | syntax/format | 具体 example + error |
| API contract | 与 schema/OpenAPI 不一致 | field/endpoint |
| Images | asset、alt、size | 文件 + 问题 |
| Locales | 缺语言或 revision 落后 | article + locale |
| Secrets | token/key | 不泄露 secret 的 finding 类型 |
没人会处理的 warning 应该被改进或删除，否则只会训练团队忽略自动化。
自动化能节省多少时间
Docs-as-Code 没有可信的统一百分比。应把假设写清楚再计算。例如每月 40 次修改，每次人工完成链接、metadata、术语、build 和结构检查需要 20 分钟，总计 13 小时 20 分钟。自动化后若每次只需 2 分钟查看结果，则约为 1 小时 20 分钟。
假设：40 × 20 分钟，对比 40 × 2 分钟。这是规划模型，不是行业 benchmark。
工业 code review 研究说明自动化重复性工作可以带来可测量收益，但不能把软件开发中的具体百分比直接套到文档团队。
先测量自己的效果，不要编造研究
TechWriters 不应在没有真正执行前声称“研究了多个项目”。可以先连续四周记录作者主动工作时间、review 等待时间、SME/editor 时间、发布后缺陷、production lead time 和 false positives。然后只自动化一组问题，比如 links、metadata 和 build，再重复测量。
这样才能形成真正有上下文和限制条件的案例研究。
人和机器应该检查不同的事情
| 机器 | 人 |
|---|---|
| 链接是否存在 | 是否真的是用户需要的目标 |
| heading 是否存在 | 结构是否围绕任务组织 |
| term 是否允许 | 对目标读者是否清楚 |
| example 是否匹配 schema | 是否解释真实任务 |
| 页面是否 build | 是否帮助用户完成工作 |
LLM 可以标记矛盾，但事实仍需通过产品、规范、测试或负责的专家确认。
什么时候变成了“工具信仰”
当流程纯洁性比参与者更重要时就开始了。如果 SME 能在浏览器里两分钟修正 parameter 名称，就没有必要要求 Node.js、本地 clone 和 rebase。应保留简单入口：网页编辑、issue、assisted authoring，或者由某个人把修改带入 Git 流程。
分阶段实施 Docs-as-Code
- 第 1 周：源文件进入 Git，历史清晰。
- 第 2 周：增加 preview 和自动 build。
- 第 3 周：启用 3–5 个真正有用的 checks。
- 第 4 周：必要时分开技术评审和编辑评审。
- 一个月后：测量 lead time、例行工作、缺陷和 warning 噪声，再决定是否继续加工具。
Docs-as-Code 的成功标准是修改、评审和发布更容易，而不是流程图更复杂。
