一句话: 让 AI 写文档,你的活是喂真材料:真实命令、真实参数、真实报错,它负责结构和补全。文档最致命的不是写得烂,是写得像真的但跑不通——所以每条安装命令都要在干净环境里验证过再发布。
很多项目代码能跑,但 README 没法看:用户不知道它解决什么问题、怎么装、怎么调、报错了去哪查。最后不是代码没人用,是文档把人挡在了门外。
README 先回答三个问题
第一屏要让人十秒内明白:这是什么,适合谁,怎么最快跑起来。
请帮我写一个项目 README。 项目名称:[名称]。 项目用途:[用途]。 目标用户:[用户]。 技术栈:[技术栈]。 请输出:简介、功能、安装、配置、快速开始、常见问题、贡献说明。
盯 AI 输出的"功能"部分:它爱写成营销话术,比如"强大灵活的配置系统"。要求每条功能后面跟一句"用户什么时候会用到",写不出来的功能直接删。
快速开始有个硬标准:用户复制粘贴所有命令,五分钟内看到第一个成功输出。超过五分钟,流失就开始了。
安装步骤要可执行
别只写"安装依赖"。版本要求、环境变量、启动命令、装失败时的常见报错,一样都不能少。
请为这个项目写安装和启动文档。 环境要求:[环境]。 命令:[命令]。 配置项:[配置]。 请写得适合第一次接触项目的开发者。
新手最常犯的错:把 AI 生成的安装步骤直接发布。AI 只能保证"看起来合理",保证不了"能跑"。发布前找台干净机器或开个容器,从第一行命令跑到服务起来,跑不通的当场修。
API 文档要有示例
开发者看 API 文档,第一眼找的就是能复制的请求示例。
请为这个接口写 API 文档。 接口路径:[路径]。 方法:[GET/POST]。 参数:[参数]。 返回:[返回示例]。 请输出:用途、请求参数、响应字段、示例请求、示例响应、错误码。
拿到输出逐个核对参数:AI 会一本正经地编出不存在的可选参数和默认值,尤其当你的参数命名比较常规时——它会按"业界惯例"替你脑补。
示例请求至少给两种形态:curl 一条,加一门你的用户最常用的语言。curl 用来快速验证接口通不通,语言示例用来直接抄进项目。
错误码要写人话
错误码不能只有 code,要回答三件事:为什么错、怎么修、能不能重试。
请为这些错误码写开发者文档。 每个错误码包括:含义、常见原因、排查步骤、是否可以重试。
成品大概长这样:
| 错误码 | 含义 | 常见原因 | 可重试 |
|---|---|---|---|
| 401 | 认证失败 | Key 错误、过期或没带 | 否,先检查 Key |
| 404 | 资源不存在 | 路径拼错、ID 已删除 | 否 |
| 429 | 触发限频 | 并发或频率超上限 | 是,指数退避 |
| 500 | 服务端错误 | 上游或依赖异常 | 是,限 2-3 次 |
"可重试"这列最有价值,直接决定调用方的重试代码怎么写——大多数文档恰恰漏了它。"排查步骤"要写到能自助:先查什么、再查什么、最后才是联系支持。每少写一步,你的支持群就多一类重复提问。
常见问题该收什么
FAQ 别让 AI 凭空想象。去翻 issue、工单和群聊,把真实被问过两次以上的问题收进来,AI 只负责把答案写清楚。凭空生成的 FAQ 都长一个样:问题没人问,答案没信息。
另外给每篇文档标"适用版本"和"最后验证日期"。读者看到半年没验证的文档会自己多留个心眼,这比让他踩完坑再来骂强。
坑与红线
- 文档漂移比没文档更坑:代码改了文档没改,用户按文档操作必然失败。把"改了行为必须改文档"写进 PR 模板。
- 示例里永远用 YOUR_API_KEY 占位。真实 Key、内网地址、员工邮箱进了文档,等于公开。
- AI 写的命令行参数、配置项名称,逐个对照源码。它编一个不存在的 --flag 不会犹豫。
- README 里别承诺没排期的 roadmap。删掉比跳票体面。
Glouth 怎么用
写 README、整理接口说明、把报错翻译成人话,用 Glouth Chat。如果项目本身要接大模型,文档里建议把 base_url 做成可配置——这样用户接 Glouth Link 的 OpenAI 兼容接口就是改一行的事,写法参考 API 接入指南。
FAQ
Q:能让 AI 直接读代码生成文档吗? 能,但只能当初稿。AI 从代码里读不出"为什么这么设计"和"什么场景别用",这两样恰恰是好文档的价值,得你补。
Q:文档写中文还是英文? 看用户在哪。面向全球的开源项目用英文;内部工具和国内用户为主的写中文。别让 AI 机翻维护双语,两份都会烂掉。
Q:有 OpenAPI/Swagger 还要手写文档吗? 要。规范文件解决"参数长什么样",手写的快速开始解决"第一次怎么跑通"。后者决定用户留不留得下来。
Q:文档多久更新一次? 跟着 release 走,发版清单里加一项"文档同步"。零散小修攒两周,文档就开始骗人了。
最后提醒
文档不是写给自己的备忘录,是给第一次接触项目的人铺路。AI 负责把材料组织成结构,你负责材料是真的——顺序反过来,就是在批量生产看起来很美的坑。
想直接上手?
这篇讲的活,打开 Glouth Chat 就能干:GPT-5.5 / Claude 等模型中文直接用,不用翻墙、不用海外卡。想给自己的 ChatGPT 账号开 Plus 的看国内充值指南;要把 AI 接进自己的工具,走 Link API。