实践指南：如何优化技术文档更好地适应大模型

核心要点

• 概述： 本文分享了优化技术文档以更好支持大语言模型(LLM)的最佳实践，这些经验来自与80多家技术团队的合作。

• 为何信任我们： 我们曾与OpenAI、CircleCI、Temporal、Mixpanel和Docker等领先公司合作，为其开发者实施基于LLM的系统。

• 为何重要： 结构合理的文档能显著提升LLM理解和回应用户查询的能力，从而优化整体开发者体验。

• 行动要点： 建立清晰的层次结构、按子产品分类文档、设计实用FAQ、提供独立代码示例、建设社区论坛，以及采纳其他实用技巧。

1. 使用页面层次目录

LLM擅长处理结构化内容，并依赖上下文提示来理解更广泛的图景。页面上清晰的标题和子标题层次结构帮助LLM理解文档不同部分之间的关系。

Temporal为其SDK文档所做的结构安排就是一个很好的例子。以Java SDK中的添加重放测试功能为例，这是与工作流执行相关的重要功能。该文档的层次结构如下：

这种结构使LLM能够在回答Java SDK中与重放测试相关的问题时更有效地导航和理解上下文。这一点尤为重要，因为重放测试也用于其他SDK。

2. 按子产品划分文档

为避免LLM混淆类似产品（如云版本与开源版本），确保在产品层面保持良好的文档层次结构也很重要。

我们发现，为每个子产品维护单独文档能显著提高LLM对上下文和用户意图的理解。

Prisma将其文档划分为三个主要产品就是一个很好的例子：

• ORM：Node.js和TypeScript ORM（核心产品）

• Accelerate：全球数据库缓存（新发布）

• Pulse：托管变更数据捕获（早期访问）

在某些情况下，按产品划分文档还允许为每个产品部署单独的LLM，可针对特定用例进一步优化。

3. 包含疑难解答FAQ

以问答形式设计的疑难解答部分是LLM的有效信息来源，它们反映了用户经常提出的问题，使LLM更容易理解并回应类似问题。

OpenAI的文档是一个很好的例子，特别是在其功能页面中，每页底部都有技术FAQ。

对LLM最有效的格式是清晰的问题后跟简明的答案。例如，结构良好的FAQ部分可能如下所示：

### [常见用户问题][简明1-2句答案]

查看LLM回应中特定来源的使用频率指标时，我们发现技术FAQ通常是最常用的来源。

4. 提供独立的示例代码片段

包含小型、独立的代码片段很有帮助，特别是对于依赖大型且通常复杂的SDK或API的产品。

例如，Mixpanel在其包含大量跟踪和分析实现代码的文档中有效使用代码片段。为展示mixpanel.people.increment方法的递增数值属性功能，他们提供了相应的代码示例。

关于包含代码的两个额外实用技巧是确保代码片段(1)在代码上方有简短描述以阐明其目的和用法，以及(2)代码内注释以解释逻辑和功能。这两点都有助于LLM进一步理解代码片段的上下文和目的。

5. 建立社区论坛

虽然与文档结构关系较小，但如果不提及建立社区论坛作为开发者和LLM获取未记录主题帮助的来源，本指南将不完整。

例如，CircleCI有一个活跃且维护良好的社区论坛，用户可以提问并从其他用户和CircleCI员工那里获得帮助。

与FAQ类似，技术论坛之所以有效是因为它反映了用户经常提出的问题。论坛还可作为官方文档尚未涵盖问题的临时解决方案。

需要注意的是，在包含论坛内容时应当谨慎。应用过滤器如仅包含标记为已解决或已接受的回复可以帮助确保内容的相关性，并包含指向原始论坛帖子的链接以确保作者得到适当引用。

6. 更多实用技巧

除上述内容外，以下是一些解决我们在LLM文档相关常见问题的实用技巧：

• 避免将文档存储在文件中：将相关内容直接保存在文档中，而非链接到PDF等文件，因为LLM解析这些文件较为困难。

• 为图像撰写文字描述：确保通过截图传达的信息也通过文字描述，因为LLM更高效地解析文本。

• 为REST API提供OpenAPI规范：提供结构化OpenAPI规范使得可以利用自定义解析器，这能改善LLM的格式处理。

• 包含示例请求和响应：在API描述中包含这些内容，为LLM提供如何使用API的具体示例。

• 定义特定缩写和术语：在文档中明确所有缩写和专业术语，以辅助LLM理解。

• 在代码示例中包含必要导入：这确保代码示例无需额外上下文即可运行。

这些技巧能显著提升LLM理解和准确回应用户查询的能力。

遵循这些指南，你可以大幅提高技术文档对LLM的实用性，最终改善开发者体验。

如果你有兴趣在自己的技术文档上测试LLM，可以注册快速演示查看效果，或者有关如何进一步优化技术文档以适应LLM的问题，请联系kapa团队。