83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
---
|
||
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 核心理念：文档即代码，代码无文档视为不完整
|