让 AI 写出人能看懂的文档:我的 3 点观察和一个 Skill

才一年时间，AI 已经接管了大半个生态：写代码、维护项目、出文档，样样都有它。

我说的不是“AI 味”，而是整份文档从结构上，就不是写给人看的。

为什么这么说？

我之前让 AI 帮我维护过一份知识库，主要给 AI 看，也由 AI 维护。整体内容结构很概括，逻辑关联也挺好。

可换我自己去看，就是难懂、费神。

现在再看 GitHub 上的说明文档，也是同样的感觉。

来看个对比：第一张是几年前的一个项目，文档一眼就能看明白它是什么、干什么用的；第二张是我最近打开的一个项目，开头就不太想往下读。

（这里只是举个例子，没有抹黑项目的意思，项目本身还是很优秀的。）

那么问题来了：AI 维护的项目和人维护的项目，差距到底在哪？

我试着分析了一下，大概有下面几个原因。文末也附上了我基于这些思考做的一个 Skill，不敢说多厉害，但起码写出来的文档，我自己能看下去。

01 AI 永远处在“全知”视角

我们自己维护项目时，踩过坑，也当过“第一次来的人”，知道新用户可能卡在哪儿。

但 AI 维护项目时，它的上下文就是整个项目本身。

它永远处在“全都知道”的状态，很难意识到 Plugin、Runtime、bootstrap 这类内部词汇，对新用户来说其实是一堵墙。

毕竟谁也不可能什么技术都懂，更不知道这个项目里有哪些坑。

02 AI 不会“偷懒”，不懂信息筛选

人脑有负载，记不住那么多，所以写文档只能挑最重要的写。

动笔前，人会把讨论过的内容、踩过的坑在脑子里过一遍，最后写下的是结论 + 一句为什么。比如：“为进一步简化用户操作，我们做了某某调整。”

但 AI 不会累。

它倾向于把当前状态完整、精确地记下来，比如提交的 Hash、边界等过程产物。

结果就是，文档成了项目状态的“快照”：

极其准确，但毫无重点。

它记下了过程，却没有转化成读者需要的东西。

03 AI 是“增量维护”，缺乏整体产品观

 AI 维护项目，通常一次只做一个任务：修个 bug，或者加个功能。

于是很多文档顶部变成了“本次更新了什么”，整个 README 被最近一次发布占满。

人则会时不时退一步想：“现在来一个新人，应该先看到什么？”然后把旧内容挪走或删掉。

站在人的角度，很多时候要做的恰恰是“删”和“不做”。

而 AI 的默认倾向是加和补。时间一长，项目就成了一层层局部正确的改动叠在一起，整体却没有主线。

AI 可以很好地执行任务，但产品这个角色，必须由人来承担。

怎么解决？

针对这些问题，我写了一个 Skill，核心目的只有一个：强制 AI 切换到用户的视角写文档。

几条核心规则：

至于“缺乏整体产品观”的问题，我的做法是：

一个低成本的自查方法

最后分享一个小技巧：用一个“干净的 AI”当新用户。

AI 的毛病是全知，但一个新开的、没有项目上下文的对话，本身就是个新人。

让它只读 README，然后说说：看完知不知道这东西是干嘛的、该怎么开始。

能说清楚这些，这份文档就过关了。

下面是我的一个完全由 AI 维护的项目 README，大家可以看看效果：

Skill 自取地址：

https://github.com/Canace22/my-skills/blob/main/human-readable-docs/SKILL.md

你最近读开源文档，有没有类似的感受？欢迎在评论区聊聊。