用 AI 写开源项目文档：README 与贡献指南

开源项目的 README 决定别人要不要继续往下看。一个几百 star 的项目，如果 README 只能看出「这是个工具」，路过的人会在十秒内关掉页面。写文档的难点不在文字，在于你太久没当过「头一回看到这个项目的人」。AI 能帮你把结构写全，但拿不准的地方，往往正是新用户卡住的地方。

先分清三类读者

打开 README 的人有三种：找替代方案的人、准备用的人、准备改代码的人。他们的路径完全不同。找替代方案的人只看开头三行和一张对比表；准备用的人找安装命令和最小示例；准备改的人找贡献指南和开发环境。文档的顺序应该按这个顺序排，越靠前的信息，服务的人越多。

很多 README 从「功能列表」开始，罗列二十个特性。这是给已经决定用的人看的，对路过的人没有帮助。功能列表放在快速开始之后更合适，前面留给「这是什么、解决什么问题」。

一句话介绍要能被搜索到

一句话介绍的结构是：做什么、给谁、和同类有什么不同。三个成分缺一个，读者就要多想一步。写成「一个轻量的、用 Rust 写的、支持增量同步的配置管理工具」，比「一个强大的配置管理解决方案」有用得多。形容词不传递信息，限定词才传递。

这句话同时承担搜索入口的作用。别人会拿「增量同步」「配置管理」这类词去搜，标题和开头一段里出现这些词，才有被搜到的可能。关键词怎么排布才自然这件事，和写商品标题是同一套逻辑：核心词放前面，限定词补在后面，不要堆。

快速开始的门槛都在细节里

最小示例要满足四个条件：依赖版本写清、命令能整段复制、有预期输出、三步之内跑起来。缺任何一条，新用户就会到 issue 里问一遍。常见的坑是命令省略了前置步骤——没说要先建虚拟环境，或者默认你已经装了某个系统库。

版本号要写具体的范围，不要写「最新版」。依赖升级会破坏示例，这是常态，写明「在某版本测试通过」比一句「请使用最新版」负责得多。

AI 写的示例有个通病：看起来很像，跑起来报错。函数名对、参数顺序错，或者用了某个包里不存在的选项。它是在模仿代码的形状，不是在验证代码的行为。每一段贴进 README 的代码，都要在干净环境里跑一遍，这条没有替代方案。

贡献指南要有可执行的动作

贡献指南的价值在于减少来回。提 issue 时该给什么（版本、系统、复现步骤、日志片段），提 PR 时该满足什么（代码风格、测试覆盖、提交信息格式），本地怎么把项目跑起来（依赖、数据、测试命令）。三块写清楚，维护者能省下大量重复回复。

再往前一步是模板。issue 模板里放几个必填项，PR 模板里放自查清单，比在文档里写「请详细描述」有效得多。人不会读长文档，但会填表单。

这张表可以当自查清单用：每一行问自己一句「一个新用户能不能只靠这一段完成这件事」，答不上来就补。

用 AI 起草的分工

合适的用法是让它做结构性的活：把散落在 issue 里的问题归成问答、把提交记录整理成变更说明、把一段中文说明改写成更短的双语版本。这类工作有明确输入，错了也容易看出来。

不合适的用法是让它凭空写功能说明。它没见过你的代码，只能根据你给的几句话推测，推测出来的描述会很像真的。给它代码片段、目录结构、真实的报错信息，比给它一段项目简介有用得多。

issue 的归类也有方法。按出现频率排是常规做法，更有用的是按原因归类——环境问题、用法误解、真实缺陷。这三类的处理方式完全不同：环境问题补文档，用法误解改设计，真实缺陷才改代码。按原因归因而非按时间罗列的思路，在这里同样成立。

它做不到的部分

AI 不知道你的项目该定位给谁。它可以写出十种介绍，但选哪一种取决于你想吸引什么人，这是产品判断不是文字工作。它也不知道新用户真正卡在哪——那些你以为显而易见的步骤，往往正是别人放弃的地方，只有翻真实的 issue 和提问记录才知道。

它更没法替你验证代码。文档里的命令能否跑通、示例是否覆盖了边界、截图是否过期，都要在真实环境里确认。文档腐化的速度比代码快，接口改一次，三处示例同时失效，而没人会主动告诉你。

README 自查

• 三行之内说清做什么、给谁、差异在哪
• 快速开始的命令整段可复制，且跑通过
• 版本号写范围，不写「最新」
• 贡献指南给模板，不只给原则
• 每段示例代码都在干净环境验证过

维护中的几个实际问题

• 中英文两份文档怎么保持一致？：以一份为主，另一份标注对应版本。改动先落到主文档，再同步翻译。两份都手改，早晚会分叉。
• 文档放 README 还是独立站点？：README 放能让人跑起来的最小集，站点放细节。README 超过两屏，新用户反而找不到安装命令。
• 老项目补文档从哪开始？：从最近十条 issue 开始。它们记录的是真实卡点，比凭空想该写什么更准。

文档写完不是终点。项目每季度做一次梳理，把过期的截图、失效的命令、改掉的参数清一遍，工作量不大但很值。定期复盘的做法可以借过来用；如果项目本身要对外讲清卖点，把一句话说到点上的方法也是相通的。