技术文档生成 Prompt：让 AI 写出人能看懂的文档

用法

把代码 / API / 功能描述粘进来，配合下面的 prompt。

Prompt

帮我把以下内容写成技术文档。不要写成说明书（「X 是一个用于 Y 的工具」），写成任务指南（「你想做 Z？这样做」）。

## 文档结构

### 这个文档解决什么问题
（1 句话：读者看完能做什么）

### 30 秒上手
（最小可运行示例，不超过 5 步，能 copy-paste 直接跑）

### 常用操作
（按使用频率排序，不是按功能分类排序。每个操作格式：）
- **做 X**：`命令或代码` → 预期结果
- **做 Y**：`命令或代码` → 预期结果

### 常见问题
（列出 3 个最可能遇到的报错，每个给解决方案。不要列「什么是 X」这种概念问题）

### 进阶
（只给链接和一句话描述，不要在这里展开。读者需要时会自己点进去）

## 规则
- 不要写「概述」「背景」「设计理念」——没人看
- 代码示例必须能直接运行，不能有伪代码
- 如果某个操作需要前置条件，在步骤里写明
- 中文输出，代码注释也用中文

---

内容来源：
（粘贴你的代码 / API 定义 / 功能描述）

效果

不加 prompt 时 AI 写的文档通常是：「X 是一个强大的工具，它提供了 A、B、C 功能……」——正确但没人看。

加了这条 prompt 后输出变成任务导向：「你想部署？这样做。你想调试？这样做。」——读者可以直接找到自己要做的事。

一个对照例子

给同一个"图片上传 API"写文档：

说明书式（没人看）：

"本模块提供图片上传能力，支持多种格式，具备完善的错误处理机制和灵活的配置选项……"

读者看完还是不知道怎么传一张图。

任务指南式（这条 prompt 的产出）：

30 秒上手

curl -F "file=@photo.jpg" https://api.x.com/upload -H "Authorization: Bearer $TOKEN"
# 返回 {"url": "https://cdn.x.com/abc.jpg"}

常见问题

• 413 Payload Too Large：单文件上限 10MB，压缩后重试。
• 415 Unsupported Media Type：只收 jpg/png/webp。

后者读者复制就能跑，报错也知道怎么办——这才是文档的目的。

为什么有效

• 指定读者：文档灾难的头号原因是「写给所有人」，写进 prompt 的受众约束会直接改变用词与深度。
• 要求「为什么」而非只写「怎么做」：没有动机说明的文档三个月后没人敢改，因为没人知道哪些是历史包袱。
• 强制给出可运行示例：示例是唯一能被自动验证的部分，也是读者真正会复制粘贴的部分。

进阶（自动化）

把文档生成挂到 CI，让「文档过期」变成可检测事件：

# 只 regenerate 变更模块对应的文档，人工 review diff
changed=$(git diff --name-only origin/main...HEAD -- "src/**")
[ -n "$changed" ] && ai-doc --files "$changed" --out docs/ && git diff --stat docs/

延伸阅读

• API 设计 Prompt — 先设计好 API 再写文档
• 什么是 Prompt Engineering — 为什么"给反例约束"比"夸要求"更有效