3.1 KiB
3.1 KiB
title, type, tags, last_updated
| title | type | tags | last_updated | |||
|---|---|---|---|---|---|---|
| Docs-as-Code | concept |
|
2026-05-01 |
Definition
Docs-as-Code 是一种将文档视为代码的实践方法论——文档使用与代码相同的工具、流程和版本控制进行管理。
Core Principles
1. 版本控制
- 文档存储在 Git 仓库中
- 所有变更通过 Pull Request 审查
- 保留完整变更历史，支持回滚
2. 自动化构建
- 文档变更触发 CI/CD 流水线
- 自动运行文档检查（spellcheck、broken links、style linting）
- 自动部署到文档托管平台
3. 协作流程
- 开发者可以直接在 IDE 中编辑文档
- 使用 Markdown / reStructuredText / AsciiDoc 等代码友好格式
- 文档评审与代码评审使用相同工具和流程
4. 自动化生成
- API 参考文档从 OpenAPI/Swagger 规范自动生成
- 代码示例从源代码自动提取
- 从代码注释（docstrings/JSDoc）自动生成参考文档
Tooling Ecosystem
Static Site Generators
- Docusaurus：Meta 出品，React 驱动，适合开源项目
- MkDocs：Python 驱动，YAML 配置，Material 主题美观
- Sphinx：Python 官方文档工具，reStructuredText 格式，扩展丰富
- VitePress：Vue 团队出品，轻量快速，Markdown 优先
Documentation Generators
- OpenAPI Generator / Swagger Codegen：从 OpenAPI 规范生成多语言 SDK + 参考文档
- JSDoc / TypeDoc：从代码注释生成 JS/TS 参考文档
- Sphinx autodoc：从 Python docstrings 自动生成参考文档
- Redoc：开源 API 文档渲染器，从 OpenAPI 规范生成可读文档
- Stoplight：商业级 API 设计 + 文档平台
Linting & Quality
- Vale：prose linter，自定义风格规则，检查文档语法和风格一致性
- markdownlint：Markdown 文件格式检查
- ** spellchecker**：拼写检查
- Link Checker：断链检测
Implementation Checklist
基础设施
- Git 仓库存储文档（与代码同一仓库或专门 docs 仓库）
- CI/CD 流水线配置文档构建和检查
- 选择静态站点生成器并完成初始配置
- 配置自动化文档生成（API docs from OpenAPI/JSDoc）
质量门禁
- Vale prose linter 规则配置
- markdownlint 检查配置
- 断链检查集成
- 拼写检查集成
发布流程
- 配置自动部署到 GitHub Pages / Read the Docs / Netlify
- 文档变更触发 PR 审查流程
- 定义文档所有者（维护者）职责
版本管理
- 配置多版本文档（对应软件版本）
- 旧版本文档归档策略（标记弃用，不删除）
Relationship to Technical Writing
Docs-as-Code 是 TechnicalWriter 的基础设施能力。engineering-technical-writer 定义了文档内容标准（Divio 系统、质量门禁、指标驱动），Docs-as-Code 提供了实现这些标准的工程化流程。两者共同构成完整的文档工程实践体系。
Sources
- engineering-technical-writer — Technical Writer Agent 核心理念：文档即代码，代码无文档视为不完整