5.7 别让文档烂尾——文档即代码
文档的困境
大多数项目的文档都面临同样的问题：
项目刚开始 → 认真写文档
开发中期 → 偶尔更新
项目上线 → 文档过时
几个月后 → 文档和代码完全对不上文档即代码的理念
Docs as Code：把文档当作代码来管理。
| 代码实践 | 文档实践 |
|---|---|
| 放在 Git 仓库 | 文档也放 Git |
| PR 必须 review | 文档也要 review |
| 有 CI 检查 | 文档也用 CI 检查 |
| 改代码提 PR | 改代码时顺便改文档 |
为什么要文档即代码
好处：
- 同步更新：代码和文档在同一个 PR
- 版本对应：每个版本的代码有对应的文档
- 可追溯：文档变更历史清晰可查
- 自动化：CI 可以检查文档完整性
本节目标
学完本节，你将掌握：
- 目录结构：如何组织文档，让它与代码结构对应
- PR 流程：如何在代码变更时同步更新文档
- 版本控制：如何用 Git 管理文档历史
- 自动化检查：如何用 CI 验证文档完整性
独立开发者的文档策略
对于一个人的项目，可以简化但不能放弃：
| 完整团队 | 独立开发者 |
|---|---|
| 详细的 API 文档 | 关键接口的说明 |
| 架构设计文档 | 简单的结构说明 |
| 开发规范文档 | 记在 README |
| 用户手册 | 关键功能说明 |
核心原则：记录未来的自己会忘记的东西。