技术文档的消费方式正在经历一场静默但深刻的范式转移。Stack Overflow 2025 年度开发者调查显示，84% 的开发者已在工作中使用 AI 工具，然而令人警觉的是，对 AI 输出准确性的不信任比例从 2024 年的 31% 攀升至 46%。这一矛盾揭示了一个核心事实：开发者正在从传统的 RTFM（Read The Fine Manual）模式，转向以 LLM 为中介的文档消费方式，但现有文档体系尚未为此做好准备。
范式转移：从线性阅读到向量检索
传统技术文档的设计假设是：开发者会按顺序阅读，能够通过视觉层级理解信息架构，并具备跨章节关联上下文的能力。然而，LLM 的工作机制完全不同 —— 它将文档切分为语义块，通过向量嵌入进行相似度匹配，再基于概率生成答案。
这种机制带来了三个结构性挑战。第一，混合主题的内容块会导致检索污染。当速率限制说明被嵌入到认证章节中时，开发者询问认证流程时可能收到混杂的速率限制信息。第二，术语不一致引发语义漂移。若文档交替使用 "API key"、"access token"、"auth credential" 三个术语指代同一概念，LLM 无法确定它们是同义词还是不同实体，只能基于概率猜测，这直接导致了那 46% 的不信任率。第三，视觉内容的语义丢失。架构图、流程图对 AI 而言只是无法解析的图片，除非配有详细的文本描述。
工程影响的三重维度
代码质量的隐性债务
当开发者依赖 LLM 生成代码时，文档的结构化程度直接决定了代码的可靠性。不规范的代码示例格式是最常见的问题源头 —— 内联代码若无围栏代码块保护，可能在 AI 处理过程中被合并或截断。开发者询问 "如何安装 SDK" 时，可能收到 npm install @company/api-client@2.1.0 and then import it 这样无法执行的混合指令。这种错误不会立即暴露，而是在集成测试阶段甚至生产环境中才显现，形成难以追溯的技术债务。
调试效率的认知损耗
AI 辅助调试的效率取决于文档能否提供精确的上下文。当文档存在术语漂移（terminology drift）—— 例如从 "master branch" 迁移到 "main branch" 但旧文档未同步更新 —— 开发者询问新术语时可能收到基于旧术语的过时流程。这种认知失调迫使开发者花费额外时间验证 AI 输出的准确性，反而降低了调试效率。支持团队报告的 "本可通过文档避免的工单" 激增，正是这一问题的外在表现。
知识传承的断层风险
更深层的隐患在于组织知识的传递机制。传统模式下，资深开发者通过阅读官方文档、源码和 RFC 形成系统性认知，再向下传递。而在 LLM 中介模式下，知识被碎片化为问答对，失去了原有的概念网络和演进脉络。新加入的开发者可能快速获得 "如何做" 的答案，却缺乏 "为什么这样设计" 的理解，长期来看削弱了团队的技术深度。
可落地的文档改造策略
面对这一范式转移，技术团队需要重构文档的生产与消费流程。以下是经过验证的工程实践：
标题层级的严格规范化
AI 系统依赖标题结构建立内容地图。跳过层级（如从 H1 直接到 H3）会破坏这一认知模型，导致检索错误。建议采用严格的层级递进：H1 用于文档标题，H2 用于主要章节，H3 用于子主题。避免使用模糊标题如 "高级功能"，改用 "OAuth 2.0 认证配置" 这样的具体描述。
术语表与一致性校验
为每个核心概念指定单一术语，并在文档中强制执行。现代文档平台（如 Redocly）提供术语一致性检查功能，可在 CI 阶段拦截混用。例如，统一使用 "API key" 后，应替换所有 "access token" 和 "auth credential" 的指代，即使这在人工阅读时显得重复。
代码示例的标准化格式
所有代码块必须使用围栏格式并标注语言标识。对比以下两种写法：
// 不利于 AI 解析
安装 SDK：npm install @company/api-client@2.1.0，然后导入使用。
// 推荐格式
安装 SDK：
```bash
npm install @company/api-client@2.1.0
在代码中导入：
import { ApiClient } from '@company/api-client';
**llms.txt 标准的采纳**
llms.txt 是一个新兴标准，通过在文档根路径提供纯文本索引文件，帮助 LLM 高效发现和导航文档内容。该文件应包含文档结构概述、关键页面链接和示例代码索引。FastHTML、Expo 等项目已实施此标准，显著提升了 AI 助手的回答准确性。
**视觉内容的文本替代**
所有图表必须配备详细文本描述。不仅要有 "上图展示了认证流程" 这样的概括性说明，还应列出完整步骤："1. 客户端向 `/auth/login` 发送凭证；2. 服务端验证后返回 JWT；3. 客户端在后续请求的 Authorization 头中携带该令牌"。这为 AI 提供了语义锚点。
**持续验证机制**
建立定期测试流程：选取关键工作流（认证、核心端点、错误处理），向 ChatGPT、Claude 等常用工具提问，验证回答的准确性和完整性。若 AI 返回过时术语或混淆概念，即表明存在术语漂移，需启动文档审计。
## 结语
从 RTFM 到 LLM 的转变不是简单的工具替换，而是知识消费基础设施的重构。文档不再仅服务于人类读者，而需同时满足机器解析的需求。这种双重受众特性要求技术写作者掌握新的约束条件：可预测的层级结构、严格的术语一致性、机器可读的代码格式。
值得强调的是，优化文档以适应 LLM 并非牺牲人类体验，而是创造双赢。清晰的结构、一致的术语、完整的示例同样提升人工阅读效率。在 84% 开发者使用 AI 工具的现实下，文档的 LLM 友好度已成为开发者体验的核心指标。技术团队应当将文档改造纳入工程优先级，否则那 46% 的不信任率将继续攀升，最终侵蚀整个开发者生态的健康度。
---
**参考来源**
- Stack Overflow Developer Survey 2025: 84% 开发者使用 AI 工具，46% 不信任 AI 输出准确性（Redocly 博客）
- llms.txt 标准规范：https://llmstxt.org/
- Svelte、FastHTML、Expo 等项目的 LLM 友好文档实践
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。