夜雨聆风
用AI写技术文档:我的效率提升5倍,但这3个坑要避开
写技术文档可能是程序员最头疼的事情之一。API文档、README、架构设计、部署指南……每种文档都有不同的写法，稍不注意就会遗漏关键信息。
自从我开始用AI辅助写文档，效率提升了至少5倍。但过程中也踩了不少坑，今天分享我的经验和避坑指南。
不要指望AI一次生成完美文档，而是让它先搭框架，你再补充细节。
Prompt示例：
我要写一个API接口文档，接口功能是用户登录。
请帮我生成文档框架，包括：接口地址、请求方法、参数说明、返回示例、错误码。AI生成的框架：
## 用户登录接口
### 接口地址
POST /api/v1/login
### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |
### 返回示例
{
"code": 200,
"data": {
"token": "xxx"
}
}
### 错误码
| 错误码 | 说明 |
|--------|------|
| 401 | 用户名或密码错误 |
然后你补充具体的参数细节、真实示例。
README是最适合AI写的文档类型。给它项目信息，让它生成初稿，你再调整。
我的做法：
- 把主要代码文件发给AI，让它理解项目
- 让AI生成README框架
- 补充安装步骤、配置说明
- 让AI润色语言，使其更通顺
技术文档最费时的不是写内容，而是调格式、排版、生成表格。让AI来做这些机械工作。
例子：
这是我的API返回数据：
{"status": "success", "data": {"id": 1, "name": "test"}}
请帮我转成Markdown表格格式AI会编造不存在的参数、过时的版本号、错误的命令。我有一次差点把AI生成的错误命令写进部署文档，幸亏测试了一下。
解决方法：
- 所有命令、代码必须亲自测试
- 版本号、参数名手动核对
- 让AI标注”需要确认”的部分
如果你的项目用了很新的框架或私有库，AI的知识库里可能没有相关信息，它就会瞎编。
解决方法：
- 先给AI提供相关文档作为上下文
- 对于冷门技术，AI只负责格式化，内容你写
- 检查AI是否”幻觉”了不存在的功能
每次写文档都从零开始，AI也不知道该遵循什么规范，生成的文档风格各异。
解决方法：
- 准备好文档模板（README模板、API文档模板等）
- 在Prompt里明确告诉AI遵循的格式
- 建立团队的文档规范文档
假设你要为一个”文件上传”接口写文档，完整流程：
Step 1：给AI上下文
我有一个文件上传接口，使用Spring Boot开发。
主要功能：上传图片文件，返回图片URL。
限制：文件大小不超过5MB，支持jpg/png格式。Step 2：让AI生成框架
请生成这个接口的API文档，包括：
- 接口地址和请求方法
- 请求参数（含Content-Type）
- 返回数据结构
- 错误码说明
- 请求示例（curl）Step 3：补充真实数据
AI生成的返回示例可能是这样的：
{
"code": 200,
"message": "success",
"data": {
"url": "https://example.com/file.jpg"
}
}你要替换成真实的返回格式，添加实际的错误码。
Step 4：润色和检查
让AI帮你润色语言，但技术细节你自己把关：
请帮我润色这段文档，使语言更专业、更易读
但不要修改技术细节现在我的技术文档工作流是这样的：
- 准备阶段（5分钟）
- 整理项目信息、代码片段
- 确定文档类型和目标读者
- AI生成框架（2分钟）
- 给AI提供上下文
- 生成文档框架和初稿
- 内容填充（15分钟）
- 补充真实参数、代码示例
- 添加截图、流程图
- 验证测试（5分钟）
- 所有命令跑一遍
- 代码示例跑一遍
- 检查链接是否有效
- AI润色（3分钟）
- 让AI优化语言表达
- 检查排版和格式
总共30分钟，以前至少要2小时。
生成README：
请为以下项目生成README.md：
项目名：xxx
技术栈：xxx
主要功能：xxx
请包括：简介、安装步骤、使用方法、配置说明、LicenseAPI文档模板：
请按照以下模板生成API文档：
接口名：xxx
请求方法：xxx
参数：xxx（请补充常见参数）
返回格式：JSON
请包含curl示例文档润色：
请润色以下技术文档，使其更专业、易读。
保持技术细节不变，优化语言表达和排版。
[粘贴文档内容]AI写技术文档的正确姿势：AI搭框架，你填内容；AI做格式，你做审核。
关键是建立自己的工作流，不是完全依赖AI，而是把AI当作效率工具。
记住3个坑：别盲信AI内容、别让AI写它不懂的、要有统一模板。避开这些坑，你的文档效率也能提升5倍。
👀 觉得有用？点个在看，让更多人看到
💬 有问题？留言区见，有问必答
👇 关注「AI防御圈」，每天懂一点AI