有了大语言模型，为什么技术文档还是错的？

一个老问题的新语境

技术文档落后于代码、充斥错误、与真实行为不符，这几乎是软件行业的顽疾。有趣的是，当大语言模型（LLM）成为开发者日常工具之后，一个值得深思的问题被重新提出：既然我们已经拥有能够读代码、写代码、总结文档的强大模型，为什么官方文档依旧频繁出错？

这个来自 Hacker News 的发问虽然简短，却触及了一个关键的认知误区——很多人默认 LLM 的出现会自动修复文档质量问题。但现实告诉我们，工具的强大并不等于问题的消失。

文档出错的根源不在于缺少工具

文档质量差，长期以来被归咎于“没人愿意写”“写了没人维护”。LLM 确实降低了撰写门槛，理论上可以根据代码自动生成说明。但文档错误的本质往往不是“写不出来”，而是以下几个更深层的问题。

真实意图无法从代码中推断

代码能表达“做了什么”，却很难表达“为什么这么做”以及“应该怎么用”。一个函数的签名可以被模型准确描述，但它背后的设计约束、边界条件、历史遗留的坑，往往只存在于开发者的脑海里。LLM 基于现有信息生成内容，当源头信息本身缺失或矛盾时，它只能产出看似合理却可能错误的文字。

文档与代码的同步机制依然薄弱

文档错误的高发区是“代码变了而文档没变”。这是一个工程流程问题，而非文本生成问题。即便用 LLM 一键生成了漂亮的文档，只要缺乏自动化的同步校验和持续集成约束，下一次代码改动后，文档照样会过时。工具提升了生产效率，却没有改变维护责任的归属。

LLM 可能让文档问题变得更隐蔽

一个被低估的风险是：LLM 生成的文档读起来更流畅、更专业，这反而会掩盖其中的错误。过去人工撰写的文档，错误往往伴随明显的粗糙感，读者会保持警惕；而模型生成的内容措辞得体、格式工整，容易让人产生“这应该是对的”的错觉。

这种“自信的错误”是 LLM 的典型特征。模型不会主动告诉你哪里不确定，它会用同样流畅的语气输出事实和幻觉。当文档中混入这类内容时，排查成本可能比传统错误更高。

这一现象在 AI 领域有专门的术语——幻觉（Hallucination）。LLM 在生成文本时并非检索事实，而是基于概率预测"下一个最可能的词"，因此它天然倾向于产出语言层面连贯、逻辑层面貌似合理的内容，即便底层事实并不存在。在代码文档场景中，幻觉尤其危险：模型可能凭空捏造不存在的参数名、错误的返回值类型，或者描述一个从未实现的功能，而这些内容在语言风格上与正确文档毫无差异。区分"模型有把握的内容"与"模型在猜测的内容"，目前仍是业界尚未解决的核心难题之一。一些缓解手段包括检索增强生成（RAG）——让模型在生成时锚定实际代码库或变更日志，而非仅依赖训练时的权重记忆——但这只能降低幻觉频率，并不能完全消除。

真正的解法是流程而非魔法

要让文档可靠，LLM 应当被定位为“辅助”而非“替代”。几个方向值得关注：

• 文档即测试：将文档中的示例代码纳入自动化测试，确保示例始终可运行，这比任何生成工具都更能保证准确性。
• 人机协同校对：用 LLM 生成初稿，由熟悉系统的工程师审校，重点补充模型无法推断的设计意图。
• 以代码为单一事实源：尽可能从类型定义、注释、接口契约中自动提取文档，减少人工复述带来的偏差。

换句话说，文档质量从来不是一个纯文本问题，而是工程文化与协作流程的综合体现。

文档即测试这一理念在实践中有成熟的落地工具。Python 生态的 doctest 模块可直接运行文档字符串中的示例并验证输出；Rust 的 cargo test 默认编译并执行所有文档注释中的代码块；而 OpenAPI/Swagger 规范则允许团队将 API 文档定义为机器可读的契约，并通过 Contract Testing 工具（如 Pact）在 CI 流水线中持续验证服务行为与文档描述的一致性。这些机制的共同逻辑是：将文档的正确性变成一个可被自动化断言的工程指标，而非依赖人工定期审查。当文档与代码产生偏差时，构建流水线直接失败，迫使开发者在合并代码前同步修正文档，从根本上改变了"文档总是最后被遗忘"的惯性。

结语

“有了 LLM，为什么文档还是错的”——这个问题的答案也许有些反直觉：因为文档的正确性从来不取决于你有多强的写作工具，而取决于团队是否建立了让文档保持真实的机制。LLM 是一把好用的笔，但它写不出团队没有记录的真相，也修不好流程中缺失的那一环。真正值得投入的，是把文档纳入可验证、可持续维护的工程体系中。