跳转至

06 - 文档生成

文档在 AI 时代不是可有可无的附属品，而是交付资产的一部分。因为当代码生成变快以后，真正决定团队能不能协作、能不能维护、能不能上线的，往往是文档质量。

这章解决什么问题

很多人理解“文档生成”还停留在：

  • 补 docstring
  • 写 README
  • 让模型帮忙润色说明

这些都对，但不够。真实交付里更重要的是：

  • 需求和边界是否写清
  • 接口和行为是否写清
  • 部署和回滚是否写清
  • 故障处理和 Runbook 是否写清

所以这一章不把文档看成“解释代码”，而是把它看成 交付和协作的外部接口。

学习目标

  • 明确不同文档在工程中的角色
  • 学会用 AI 快速生成高质量初稿
  • 学会把 README、API 文档、Runbook、交付说明串成一套资产
  • 能把文档工作转成真正的项目价值

文档的 5 种层次

层次 作用
代码内文档 帮助理解局部实现
开发文档 帮助接手和继续开发
使用文档 帮助调用或操作系统
运维文档 帮助发布、排障、回滚
交付文档 帮助面试、汇报、团队协作

大多数人只补了前两层，真正值钱的常常是后两层。

AI 最适合帮你生成哪些文档

AI 很适合做：

  • README 初稿
  • API 文档初稿
  • 安装和运行说明
  • 变更说明
  • FAQ 草稿
  • PR 描述和交付摘要

AI 不适合直接完全替代你写：

  • 架构决策
  • 真实上线步骤
  • 回滚条件
  • 故障处置流程

因为这些内容必须和真实系统一致。

最有价值的 6 类文档

如果你想把项目做成真正可交付的作品，下面这 6 类文档的优先级通常最高。

1. README

好的 README 应至少回答：

  • 这是什么系统
  • 解决什么问题
  • 如何运行
  • 目录怎么组织
  • 当前已知限制是什么

README 的最大价值不是“写得好看”，而是让别人能快速上手。

2. API / 接口文档

至少要写清：

  • 输入输出
  • 错误码
  • 认证方式
  • 限流和超时
  • 示例请求和响应

如果你做的是 AI 系统，还应该补：

  • 模型或版本
  • 输出不确定性
  • fallback 行为

3. 运行与部署文档

要回答：

  • 如何本地启动
  • 如何配置环境变量
  • 如何跑测试
  • 如何发布
  • 如何回滚

这类文档在项目和实习里特别值钱。

4. Runbook

这是很多求职项目缺失、但 2028 很有价值的文档。

Runbook 应回答：

  • 出现什么告警
  • 如何定位
  • 先看什么指标
  • 如何临时止血
  • 什么条件下回滚

如果你能在项目里补这类文档，系统设计面试也会更强。

5. 评测和实验文档

适用于 AI 项目：

  • 测了什么
  • 指标是什么
  • 数据集是什么
  • 结果如何
  • 还存在哪些 bad cases

这比“效果很好”这种描述强得多。

6. 变更与交付文档

例如：

  • 这次改了什么
  • 为什么改
  • 风险是什么
  • 需要同步什么配置
  • 如何验证

这类文档非常适合和 AI Coding 工作流结合。

一个好的文档生成流程

Text Only
先明确读者是谁
→ 明确文档目的
→ 收集真实信息
→ 让 AI 生成初稿
→ 人工核对关键事实
→ 补齐示例、风险和限制
→ 放进仓库和交付流程

关键点在于：AI 生成的是初稿，事实校验必须由你负责。

4 类常用文档模板

模板的价值不在套格式，而在于让你在高频场景下稳定补齐关键信息。

模板 1：README

Markdown
# 项目名称

## 项目目标
[解决什么问题]

## 核心能力
- 能做什么
- 当前边界是什么

## 快速开始
- 环境要求
- 安装
- 启动
- 测试

## 目录结构
[主要目录说明]

## 已知限制
[当前未解决的问题]

模板 2：接口文档

Markdown
## 接口名称

### 路径
`POST /api/search`

### 说明
[做什么]

### 请求参数
[字段、类型、说明]

### 响应
[字段、类型、说明]

### 错误处理
[常见错误码]

### 示例
[请求/响应示例]

模板 3：Runbook

Markdown
## 告警名称
[例如：RAG 检索超时率升高]

## 现象
[看到什么问题]

## 排查顺序
1. 看网关错误率
2. 看检索服务延迟
3. 看向量库健康状态

## 临时止血
- 降级到关键词检索
- 关闭 rerank

## 回滚条件
[什么情况下需要回滚]

模板 4：交付说明

Markdown
## 本次改动
[改了什么]

## 改动原因
[为什么改]

## 风险
[哪里可能出问题]

## 验证
- lint
- test
- smoke test

## 回滚
[如何恢复]

AI 文档生成最常见的 6 个问题

先看清这些问题，才能避免文档越写越多、信息量却越来越低。

1. 事实错误

例如写了根本不存在的接口、参数或命令。

2. 只会复述代码，不会解释目的

这类文档可读性很差。

3. 看起来完整，实际上缺关键步骤

尤其是部署和回滚文档里很常见。

4. 示例不能运行

文档如果不能跑，价值会大幅下降。

5. 没有写边界和限制

这会让使用方误解系统能力。

6. 版本不同步

这是最伤文档信任度的问题。

文档生成最值得要求 AI 输出什么

除了正文本身，建议同时要求它输出：

  • 假设了哪些前提
  • 哪些内容可能需要人工核对
  • 缺失了哪些真实信息
  • 哪些命令或示例需要实际验证

这会显著提高你校对效率。

对 AI 项目最有价值的文档组合

如果你做的是 RAG / Agent / AI4SE 项目，我最建议补下面 5 份：

  • README
  • 架构说明
  • 评测说明
  • Runbook
  • 交付变更说明

这 5 份一齐存在，项目成熟度会明显上一个台阶。

2028 面试里怎么讲文档工作

不要说：

Text Only
我补了项目文档。

更好的表达是：

Text Only
我把项目文档从简单 README 扩展到了 API 说明、评测文档、Runbook 和交付说明，目的是让系统不仅能跑，还能被接手、被验证、被上线和被回滚。

这体现的是工程成熟度，而不是文字工作。

简历怎么写

差的写法：

Text Only
完善项目文档。

好的写法：

Text Only
为仓库感知 AI 助手补齐 README、评测说明和 Runbook，明确启动方式、验证流程、告警处置与回滚步骤，提升项目可交付性和可复现性。

一个简单文档 checklist

  • 读者是谁
  • 文档目标是什么
  • 示例是否真实可运行
  • 关键事实是否核对过
  • 是否写了限制和风险
  • 是否和当前代码同步

本章小结

  • 文档生成的真正价值，是让项目变成可接手、可上线、可维护的资产
  • AI 最适合生成初稿，但关键事实、上线步骤和回滚条件必须人工核对
  • 2028 更高价值的文档，不只是 docstring，而是 README、Runbook、评测说明和交付说明

下一步