文档即代码是什么

文档即代码（Docs as Code）把文档当代码一样管理：与代码放在同一仓库、走同一套分支与评审流程，用 Markdown 等纯文本格式书写，由 CI 检查格式与链接并自动构建发布。核心收益是文档更新与代码变更同步发生，从机制上减少“文档过期”，也让修订历史与责任人可追溯。

推行要点

建议先选一类文档试点（通常是 API 文档或运维手册），把仓库结构、写作模板与 PR 检查项固化下来再逐步扩展；文档与代码分属不同仓库时，要用链接和自动同步任务保持关联，避免两边各写一份。还要指定文档责任人，否则改动多由提交者自查，质量完全取决于个人习惯。

基本信息

典型使用场景

• API 文档随接口变更在同一 PR 中更新，评审时一并检查
• 运维 Runbook 纳入仓库，故障后修订留有历史记录
• 架构决策记录与代码同源，便于回溯当初的设计理由
• 文档站自动构建发布，避免手工上传导致版本错位
• 新人入职：克隆仓库即可拿到与当前版本一致的文档
• 多语言或对外文档：用同一套源码生成不同站点

一次文档改动流程

git checkout -b docs/mq-limit      # 新建分支，勿直接改主干
vim docs/message-queue.md          # 修改正文与示例
mkdocs serve                       # 本地预览渲染效果
git commit -m 'docs: 补充消息队列限流说明'
git push origin docs/mq-limit      # 发起 PR，走评审
# CI 侧常见检查（任一失败即阻塞合并）
markdownlint docs/                 # 标题层级与格式
lychee --offline docs/             # 站内链接有效性
mkdocs build                       # 能否成功构建

内容类型适配