AI 文档之殇：为什么没人读自动生成的文档

AI 已经悄悄渗入了我们日常的开发工作流。它写代码、生成测试、总结拉取请求，而且现在比以往任何时候都更多地在写文档。从自动生成的 Confluence 页面到 AI 生成的 README，文档的生成速度前所未有。

但更快并不总是意味着更好。

当涉及到技术文档，特别是 Confluence 和 README 时，AI 往往生成的内容看似完整，但并不真正易于消化。这就是问题开始的地方。

AI 在文档中的承诺

让我首先明确说明这一点。我不是在劝阻使用 AI。

事实上，我也难辞其咎地大量使用了它。

这很轻松。不费力气。快得惊人。一个本来需要花费几个小时的 Confluence 页面在几分钟内就完成了。感觉很有效率，一段时间内确实如此。

AI 真正擅长于从无到有创建结构、生成一致的模板、将代码转化为文本，以及填充显而易见的部分，这样你就不会面对一个空白页面。

对于时间紧张的团队来说，这种速度是很难反驳的。

问题显现的时刻

问题没有立即显现。

当我大约一个月后重新访问其中一份 AI 生成的文档，却无法理解它的要点时，问题才变得明显。

文字是我的。页面是完整的。但意思并没有留下印象。

我发现自己在重新阅读段落，上下滚动，试图重建这个系统实际上做了什么以及为什么。那时我恍然大悟。文档已经被写下来了，但它没有被准确表达。

文档的真正目的

文档的主要目的不是在页面上放置文本。

它是以一种易于消化、易于保留，并且在几个月甚至一年后仍然清晰的方式来表达想法。

好的文档经得起时间的考验。

你应该能够在一年后回到它，快速浏览几个部分，然后立即记起这个东西做什么、为什么存在，以及你应该注意什么。

AI 生成的文档往往在这个测试中失败。

即使我们要求更多 Why 和 How，结果仍然有所欠缺

对 AI 文档批评的常见回应是简单地改进提示词，并询问为什么和如何。

虽然这有帮助，但输出通常仍然冗长、抽象，充满了听起来正确但没有在记忆中留下深刻印象的概念。

你最后得到的文档看起来很全面，但难以消化。它要求读者集中注意力，而不是引导读者的注意力。

大多数读者不会费力理解这些，特别是在 Confluence 中。

冗长不等于清晰

AI 经常把长度与有用性等同起来。

你得到的不是简洁的解释、清晰的心智模型和简单的指导（比如"除非你在做 X，否则可以忽略这个"），而是长段落、用不同方式重复的观点，以及大量没有粘性的词汇。

因为 Confluence 页面很少被清理，那种冗长并不会被修复。它只是悄悄地躺在那里，无人阅读。

对话式文档的力量

最有效的 Confluence 页面和 README 读起来就像一位队友在向你解释事情。

它们预料到了困惑。它们在使用技术术语之前先用简洁语言。它们告诉你什么重要，什么不重要。

AI 风格：此服务抽象了与用户相关数据的持久化层。

人工风格：此服务存在的目的是让应用的其余部分不需要知道用户数据如何存储。如果我们曾经更改了数据库，这是唯一一个我们需要更新的地方。

相同的含义。截然不同的体验。

人类仍然比 AI 做得更好的地方

人类捕捉权衡和现实。

他们写的内容像这样：这不是理想的选择，但在当时是最安全的选项，或者我们在这里优化了速度，或者小心改动这个，因为它以前破坏过东西。

AI 倾向于掩盖这些边界。人类则记录它们，这正是真实价值所在。

人类还会添加代码中不存在的背景信息。过往事件、组织约束、在压力下做出的决策。没有这些背景，文档在技术上可能是正确的，但在实际上没有帮助。

而且人类会减少读者的焦虑。

他们写的内容像这样：如果这感到困惑，那是正常的，你可能不需要动这个，或者如果你卡住了就去找这个团队谈。AI 很少自然地这样做。

应该如何使用 AI

这不是对 AI 的警告。这是对未经审查的 AI 的警告。

AI 是一个很好的起点，但它不应该是最终作者。

一个更健康的方法是让 AI 生成初稿，然后由人类删除冗长部分、移除不必要的术语、添加背景和观点，并用对话式的方式重写部分内容。

一旦某样东西出现在 Confluence 或 README 中，它往往会在很长时间内悄悄地躺在那里，无人阅读。这正是为什么它值得被认真对待。

AI 帮助我快速写出文档。它也教会了我把速度误认为是清晰是多么容易。

文档不是关于写下所有内容。它是关于以一种易于记忆的方式表达正确的事情。

AI 可以解释存在什么。人类解释什么重要。

使用 AI。绝对可以。只是不要让它的输出在没有经过人工审查的情况下成为永久的，因为不易消化的文档不会消退。

它停留。无人阅读。永远。

---

一些评论可能仅对登录用户可见。登录以查看所有评论。

对于进一步的操作，你可以考虑屏蔽此人和/或举报滥用。