开篇
让 AI 写技术文档，最常见的提问是：
text
请帮我写一份接口文档。得到的结果通常很长，却不一定好用：
- 把代码注释改写一遍。
- 充满"系统能够提升效率"这类空话。
- 没有写清楚参数、错误码和调用示例。
- 把 AI 猜测的内容当成了项目事实。
技术文档的价值，不是字数多，而是让读者更快完成一个动作：调用接口、部署服务、排查故障，或者接手模块。
这篇文章分享我的一个做法：
先确定文档要帮助谁完成什么任务，再让 AI 补齐结构和表达。
一、先明确文档要解决什么问题
在让 AI 动笔前，我会先补充三个信息：
| 信息 | 要回答的问题 |
|---|---|
| 读者 | 谁会阅读这份文档？ |
| 任务 | 读者看完后要完成什么操作？ |
| 范围 | 哪些内容必须写，哪些内容不写？ |
例如，"写用户登录接口文档"太宽泛，可以改成：
text
读者是前端开发者。
目标是让前端能够完成登录请求、处理成功响应和展示常见错误。
范围只包含 HTTP 接口，不介绍数据库实现和登录算法。这一步能够明显减少无关内容，也能避免 AI 把文档写成技术说明书。
二、我会固定使用这 6 个文档部分
对于接口、工具类和内部服务，我通常只保留下面六部分：
- 功能说明：一句话说清楚它做什么。
- 使用前提：权限、环境变量、依赖服务等。
- 调用方式：请求方法、路径、请求头和参数。
- 返回结果：成功结构、字段含义和示例。
- 异常处理：常见错误、原因和处理建议。
- 完整示例：让读者可以直接改参数验证。
如果某一部分确实不适用，就删除它，不要为了完整而硬凑章节。
例如，下面这句话就比"支持用户登录功能"更有用：
text
POST /api/auth/login
用于校验邮箱和密码，成功后返回 24 小时有效的访问令牌。三、让 AI 先提取事实，再组织文字
我不会直接让 AI 根据一段代码生成最终文档，而是分两步进行。
第一步，提取事实：
text
请阅读下面的接口代码，只提取代码中能够确认的事实，不要补充猜测。
请整理：
1. 请求方法和路径。
2. 请求头和参数。
3. 成功响应字段。
4. 代码中明确处理的异常。
5. 依赖的配置或外部服务。
无法确认的内容统一标记为"待确认"。第二步，再组织文档：
text
请根据上一步确认过的事实，生成一份面向前端开发者的接口文档。
要求：
1. 使用 Markdown。
2. 先给最小可用调用示例。
3. 参数使用表格展示，字段说明要具体。
4. 错误码写明原因和处理建议。
5. 不要重复解释代码实现。
6. 不要编造上一步没有确认的字段、状态码或业务规则。
7. 不确定的内容保留"待确认"标记。
8. 控制在 800 字以内。"提取事实"和"组织表达"分开后，AI 更不容易把猜测写成结论。
四、一个简短的接口文档示例
经过整理后，文档应该接近下面这种形式：
用户登录
校验用户邮箱和密码，成功后返回访问令牌。
http
POST /api/auth/login
Content-Type: application/json请求参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string | 是 | 用户邮箱 | |
| password | string | 是 | 用户密码 |
请求示例：
json
{
"email": "dev@example.com",
"password": "your-password"
}成功响应：
json
{
"token": "eyJhbGciOi...",
"expiresIn": 86400
}常见错误：
| 状态码 | 原因 | 处理建议 |
|---|---|---|
| 400 | 参数缺失或格式错误 | 检查邮箱和密码 |
| 401 | 邮箱或密码错误 | 提示用户重新输入 |
| 500 | 服务内部异常 | 记录请求标识并联系后端 |
这里没有介绍数据库表结构，也没有解释令牌内部算法，因为它们与当前读者的调用任务无关。
五、AI 写完后，我只检查这 5 件事
文档生成后，不要只检查语句是否通顺。我会重点确认：
text
[ ] 示例能否与当前接口真实交互？
[ ] 参数名、类型和必填项是否与代码一致？
[ ] 返回字段是否真的存在？
[ ] 错误码和处理建议是否经过项目确认？
[ ] 是否混入了没有依据的内容？其中最重要的是"示例能不能跑"。
技术文档最容易出现的问题，不是错别字，而是示例已经过时。接口变更后，至少要把 README、接口文档和自动化测试一起检查一遍。
六、避免技术文档变成废话的规则
我会给 AI 加上下面几条限制：
- 每个段落只表达一个结论。
- 能用表格说明的内容，不写成长段落。
- 删除"非常方便""大幅提升效率"等无法验证的形容词。
- 先给操作步骤，再补充必要背景。
- 不解释读者已经能从代码中直接看出的内容。
- 没有证据的内容标记为"待确认"，不擅自补全。
可以把它总结为一句话：
技术文档不是展示 AI 文采，而是降低读者完成任务的成本。
总结
让 AI 写技术文档时，我会遵循下面的顺序：
text
确定读者和任务
↓
提取已确认事实
↓
套用精简结构
↓
补充示例和错误处理
↓
人工核对并实际验证- 先定义文档要帮助谁完成什么任务。
- 让 AI 区分已确认事实和待确认内容。
- 用固定结构减少遗漏，用限制条件减少废话。
- 文档示例必须和真实代码、接口保持一致。
下一篇文章，我们将继续学习：
《3 个能立刻复用的 AI 编程工作流》
✍坚持原创，求关注，点赞，收藏