文档生成

好代码降低读码成本，但 接口契约、运行方式、架构决策 仍需要文档。路线图 documentation-generation 节点关注：README、API 文档、变更说明如何 与代码同步，而不是上线后没人敢改的旧 wiki。

学习目标

• 区分 README、API 文档、ADR 的受众与更新时机
• 知道 OpenAPI / Javadoc 等生成思路
• 将文档质量纳入 cq-reviews 检查项

文档分层

类型	读者	典型位置
README	新人、运维	仓库根、模块根
API 文档	前后端联调	OpenAPI、Swagger UI
架构决策	团队长期	ADR、docs/
课时/内容	学习者	content/ + outline.yaml

CodeRoadMap 的 content/课程/*/outline.yaml 即 课程索引文档；改 slug 必须同步，否则链接 404。

README 写什么

最小集合：

1. 是什么（一句话）
2. 如何跑（prerequisites、install、dev 命令）
3. 如何测（链到 testing-essentials）
4. 如何贡献（分支、PR，链到 git-essentials）

避免：复制粘贴整本框架教程；应链到官方或本站 track。

API 文档生成

Spring Boot 常用 springdoc-openapi：Controller 注解 → /v3/api-docs → Swagger UI。好处：单源真相在代码，改接口 PR 必须更新注解或 DTO 说明。细节见 spring-boot-essentials（若已覆盖 REST 文档）。

前端 TypeScript 可用类型 + 注释生成 SDK 说明；与 backend OpenAPI 对齐可减少联调摩擦。

文档债务

• 截图过期、端口写错 → 新人第一天就卡住
• 「TODO 补文档」永不过期 → 纳入 cq-debt

用 AI 起草 README 时，必须本地跑通命令再 merge，见 ai-coding-essentials 类实践。

练习

• 读 CodeRoadMap 根 README，标一条可改进的运行说明
• 打开 backend 任一带 @RestController 的类，看是否已有 OpenAPI 注解