AI、Confluence Docs 和 READMEs：为什么 AI 编写的文档最终未被阅读
Source: Dev.to
请提供您希望翻译的完整文本内容，我将按照要求将其翻译成简体中文并保留原始的格式、Markdown 语法以及技术术语。谢谢！
AI 在文档编写中的前景
让我先明确地说：我并不是在劝阻使用 AI。事实上，我自己也大量使用过它。它使用起来轻松、毫不费力，而且出乎意料地快。原本需要数小时才能完成的 Confluence 页面在几分钟内就出现了。那种感觉很有成效，短时间内它确实如此。
AI 在从无到有创建结构、生成统一的模板、将代码转化为文字以及填补显而易见的章节方面确实非常有用，这样你就不必盯着空白页发呆。对于时间紧迫的团队来说，这种速度几乎无可争议。
当它猛烈冲击的那一刻
问题并没有立刻显现。大约一个月后，我重新打开其中一份 AI 生成的文档时才意识到它的存在，却无法把握其要旨。文字是我的，页面完整，但意义却没有留下来。
我发现自己反复阅读段落，上下滚动，试图重建系统到底做了什么以及原因。就在这时，我恍然大悟：文档已经写好，却没有被清晰表达。
文档的真实目的
文档的主要目的并不是把文字放在页面上，而是以易于阅读、易于记忆的方式阐述思想，并且在数月甚至一年后仍然保持清晰。优秀的文档能够经受时间的考验。你应该能够在一年后再次打开它，快速浏览几个章节，立刻记起这个东西的功能、存在的原因以及需要注意的事项。
AI 生成的文档往往未能通过这一测试。
Even When We Ask Why and How, It Is Still Not Quite There
对AI文档批评的常见回应是只要更好地提示它，并询问原因和方式。我也尝试过。虽然有帮助，但输出仍然往往过于冗长、抽象，并且充斥着听起来正确却无法在记忆中落地的概念。
于是你得到的文档看似完整，却难以消化。它要求读者集中注意力，而不是引导注意力。大多数读者不会在Confluence里坚持阅读。
Verbosity Is Not the Same as Clarity
AI 常常把篇幅等同于有用性。与其提供简短的解释、清晰的思维模型以及诸如 “you can ignore this unless you are working on X” 这样的简单指导，你会得到冗长的段落、以不同方式重复的想法，以及大量却几乎没有黏性的文字。
由于 Confluence 页面很少被清理，这种冗长不会被修正——它只会静静地在那里，没人阅读。
对话式文档的力量
最有效的 Confluence 页面和 README 就像同事在向你解释一样。它们会预见可能的困惑，先使用通俗语言再给出技术术语，并告诉你哪些是重要的，哪些不是。
AI 风格：
This service abstracts the persistence layer for user‑related data.
Human 风格：
This service exists so the rest of the app does not need to know how user data is stored. If we ever change the database, this is the only place we should need to update.
意义相同，体验却大相径庭。
人类仍然优于 AI 的方面
- 人类捕捉权衡和现实，写下诸如“这并不理想，但当时是最安全的选项”，或“我们在这里优化了速度”，或“更改此项要小心，因为之前它已经导致问题”。AI 往往会把这些边缘抹平；人类记录它们，这才是真正的价值所在。
- 人类添加代码中不存在的上下文：过去的事件、组织约束、在压力下做出的决定。没有这些上下文，文档可能在技术上是正确的，却在实际使用中毫无帮助。
- 人类通过安抚性备注来减轻焦虑，例如“如果这让你感到困惑，那是正常的；你可能不需要动它”，或“如果卡住了，请联系这个团队”。AI 很少自然地这样做。
如何使用 AI
这并不是对 AI 的警告；而是对 未经审查的 AI 的警告。AI 是一个极好的起点，但它不应成为最终的作者。
更健康的做法是让 AI 生成初稿，然后由人类进行：
- 删除冗长
- 去除不必要的行话
- 添加上下文和观点
- 以对话式的方式重写各段落
一旦内容被放入 Confluence 或 README，它往往会静静地待在那里，长时间未被阅读。这正是它需要细心对待的原因。
最终思考
AI帮助我快速编写文档。它也让我意识到把速度误认为清晰是多么容易。文档并不是把所有内容都写下来，而是要以能让人记住的方式阐述正确的要点。
AI可以解释现有的事物。人类解释重要的事物。
使用AI。绝对可以。但不要让它的输出在未经人工审阅的情况下成为永久内容，因为不可读的文档不会消失——它会一直存在，未被阅读，永远停留。