---
title: "Docs-as-Code"
type: concept
tags: ["documentation", "devops", "methodology"]
last_updated: 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 核心理念：文档即代码，代码无文档视为不完整