Diátaxis 文档框架：教程、指南、参考与解释

技术文档经常出现一种结构性故障：教程里塞满概念解释，API 参考页写成操作指南，部署手册又夹杂产品背景。每一段内容单独看都可能正确，读者却很难在需要的时候找到能直接使用的信息。

Diátaxis 是一套专门处理这类问题的技术文档框架。它把文档分为教程（Tutorials）、操作指南（How-to guides）、参考（Reference）和解释（Explanation）四种形式，并用两个问题判断一段内容应当属于哪里：读者是在学习还是工作？内容是在指导行动还是提供认知？

这套方法的价值不在于给文档目录换一组名称，而在于把用户意图、文章写法和信息架构放到同一套坐标系里。对于 API、SDK、云服务、DevOps 平台和开源项目，四类文档可以直接对应到日常维护工作。

四类文档分别解决什么问题

Diátaxis 官方模型有两个维度。行动与认知描述内容形态，学习与工作描述用户所处的状态。两条轴交叉后形成四个区域。

同一个主题可以出现在四种文档里，但写法和目标不同。以“身份认证”为例：教程可以带着新用户创建第一个 API Token；操作指南可以处理 Token 泄露后的轮换；参考页列出字段、权限和错误码；解释文章讨论短期 Token、刷新 Token 与权限边界的设计关系。

划分依据是用户要完成的事情，不是文档涉及的产品模块。把所有内容按“认证”“部署”“监控”这样的功能名分组，往往会让四种需求重新混在一起。

教程：让读者在实践中获得技能

教程是学习体验。读者在作者的引导下完成一项有意义、可达成的实践活动，目标是获得技能和信心，产物本身只是学习过程的载体。

一篇面向初学者的 SDK 教程可以这样设计：创建项目，安装依赖，配置最小凭据，发出第一次请求，读取响应，再增加一个可见的小功能。每一步都应该产生可以观察的结果，让读者能够把自己的操作和结果联系起来。

教程的写作重点有四个：

1. 先展示终点。 开头说明读者将完成什么，例如创建一个可以读取任务列表的命令行程序。读者需要知道每个操作在整体路径中的位置。
2. 小步推进。 一次只引入一个新动作或概念。命令、文件和配置不要在同一段里成批出现，否则出错时很难定位。
3. 尽早给出可见结果。 第一次成功运行、第一次 API 响应、第一次页面变化，都应该成为学习反馈。
4. 解释保持克制。 教程的主线是完成实践。需要深入理解的内容放到解释文档，用链接连接两种阅读路径。

教程并不适合承载全部边界条件。初学者需要一条稳定的学习路径，过多分支会让这条路径失去节奏。版本变化也会首先冲击教程，因为端到端流程中的一处改动可能影响后面的每个步骤。

判断一段内容是否属于教程，可以问：读者是否需要跟着作者一步一步做？读者是否正在获取技能？两个答案都为“是”，教程形式才成立。

操作指南：围绕真实任务组织步骤

操作指南面向已经具备基本能力、正在处理具体工作的人。它的标题通常带着明确目标，例如“如何配置生产环境的数据库连接池”“如何排查 Webhook 重试堆积”“如何为 CLI 增加自定义认证后端”。

操作指南的中心是问题和结果，不是产品功能清单。它可以跨越多个模块，把用户为了完成任务所需要的命令、判断和配置串起来。工具在这里是手段，任务才是组织线索。

写操作指南时，可以先列出以下内容：

• 任务的起点：读者已经有什么环境、权限和输入。
• 成功条件：完成后能观察到什么结果。
• 必要路径：哪些动作必须按顺序执行。
• 判断分支：哪些错误现象需要选择不同处理方式。
• 退出点：什么时候可以停止，什么时候应转到排障或参考文档。

例如，“部署服务”适合作为一个宽泛主题，却不适合作为操作指南标题。更具体的任务可以是“如何在 Docker Compose 中替换服务镜像并保留数据库卷”。正文可以包含检查当前容器、备份配置、修改镜像、执行滚动更新、确认健康检查和回滚的步骤；Docker Compose 每个字段的完整语义应链接到参考页。

操作指南与教程最容易混淆。教程帮助读者学习，允许作者控制环境、控制节奏，并用小步骤建立技能。操作指南帮助熟练用户完成工作，允许用户从中间步骤进入，也允许根据现场条件调整路径。把教程写成操作指南，初学者会缺少背景；把操作指南写成教程，熟练用户会被迫阅读不需要的教学过程。

参考：给正在工作的用户一张准确的地图

参考文档是技术事实的有序描述。它服务于正在工作的用户，目标是准确、完整、稳定、便于查阅。API、类、函数、CLI 子命令、配置项、环境变量、错误码和协议字段都属于参考内容。

参考页应尽量保持中性。用户查找 timeout_ms 的默认值时，需要看到字段类型、默认值、允许范围、版本变更和错误行为，不需要在字段说明中穿插一段关于团队设计理念的讨论。背景和取舍应放到解释文章，具体任务应放到操作指南。

参考文档的结构最好映射产品或代码的结构。一个 Go 服务的参考目录可以贴近包、接口和配置层次：

reference/
  cli/
    auth.md
    deploy.md
  api/
    authentication.md
    jobs.md
    webhooks.md
  configuration/
    server.md
    database.md
  errors.md

每个参考条目使用稳定格式，读者才能快速定位信息。以 HTTP 接口为例，可以固定为：方法与路径、用途、认证方式、请求参数、请求示例、响应字段、错误码、幂等性和版本信息。自动生成部分适合交给 OpenAPI、代码注释或类型系统，但自动生成并不能代替人工检查示例和任务链接。

参考页也需要示例。示例的作用是帮助读者看懂字段如何组合，不能借机扩写成完整教程。一个 curl 示例足以说明 Header、请求体和响应形态，具体的生产部署路径可以链接到对应的操作指南。

解释：回答“为什么这样设计”

解释文档提供背景、上下文和概念之间的联系，服务于想建立整体理解的读者。它可以讨论架构取舍，也可以呈现多个视角和适用边界。

例如，API 认证参考页只需要列出 Token 类型、Header 格式和错误码；解释文章可以讨论为什么系统采用短期访问 Token、刷新 Token 和权限范围的组合，说明安全性、可撤销性、用户体验和服务端状态之间的关系。读者在这里获得的是理解框架，操作步骤仍然应该回到操作指南。

解释文档的标题可以使用“关于……”的形式，例如“关于 Webhook 至少一次投递”“关于服务端限流和客户端退避”“关于事件驱动架构中的幂等性”。这能提醒作者：文章的任务是建立联系，不是把读者带过一条固定命令序列。

解释和参考也容易混在一起。参考回答“字段是什么、参数允许哪些值、接口返回什么”；解释回答“这些字段为什么存在、它们和系统其他部分怎样互相影响”。参考需要权威和精确，解释允许更宽的视角，但仍然必须与产品事实一致。

用两个问题给现有文档分类

实际项目很少从空目录开始。更有效的做法是选一页现有文档，逐段检查，而不是先建好四个空目录再把旧内容硬塞进去。

可以使用下面的判定表：

组合后就能得到归属：指导行动并服务学习，是教程；指导行动并服务工作，是操作指南；提供认知并服务工作，是参考；提供认知并服务学习，是解释。

这个判断可以下沉到句子级别。操作指南中突然出现一大段系统历史，通常是解释内容闯入了行动路径；参考页里出现“现在执行以下命令”，通常是操作指南内容；教程里连续出现多个“原理上……”段落，可能需要把背景拆到解释文档。

完成分类后，再用链接把它们连起来。教程在需要时链接解释，操作指南链接参考，解释链接教程和真实任务，参考链接具体的任务路径。链接负责建立不同意图之间的明确出口，页面仍然各自保持主题集中。

API 与 DevOps 项目的落地方式

以一个提供任务编排 API 的服务为例，可以按用户问题规划文档，而不是按内部包名复制目录：

docs/
  tutorials/
    first-job.md
    local-development.md
  how-to/
    rotate-api-token.md
    retry-failed-job.md
    deploy-with-compose.md
    diagnose-webhook-delivery.md
  reference/
    api/jobs.md
    api/webhooks.md
    cli.md
    configuration.md
    errors.md
  explanation/
    authentication-model.md
    job-lifecycle.md
    retry-and-idempotency.md

这份目录只是初始形态。实际维护中，可以从一篇最常用的部署文档开始，检查它是否混入了参数百科、架构背景和新手教学。把不同意图的内容拆开，补上链接，再处理下一页。随着页面内部逐步成形，目录结构自然会变得清晰。

每种文档还可以配一套验收标准：

教程验收： 新用户能从干净环境走通；每一步有预期结果；失败时知道检查哪里；过程中的概念数量可控。

操作指南验收： 标题对应一个真实任务；起点和成功条件明确；步骤能适应常见环境差异；不把完整参考信息塞进主路径。

参考验收： 字段和行为准确；命名和章节结构稳定；默认值、范围、错误和版本信息齐全；示例不会暗示未声明的行为。

解释验收： 文章围绕一个“为什么”组织；概念之间的联系明确；观点和事实分开；读者能理解设计取舍及其边界。

迭代维护：从一页开始，每次做一个改进

Diátaxis 的工作流不要求先完成一份宏大的重构计划。官方建议把它当作工作指南：观察眼前的文档，找出一个可以改进的地方，执行一个具体动作，然后重复。

这套节奏适合持续变化的软件项目。一次提交可以只完成一件事：把部署页面中的错误码段落移到参考页，或者给一个 CLI 参数补上默认值。改动提交后，读者立刻获得收益，维护者也能从下一次反馈中发现新的问题。

可以把每轮维护压缩成四步：

1. 选一页，最好从用户最常访问或团队最近刚修改的页面开始。
2. 询问这页当前服务的用户需求，以及哪些句子偏离了这个需求。
3. 选择一个最小改动，例如拆分一段、补一个结果示例、改一个标题或增加一个链接。
4. 发布改动，再进入下一轮。

文档质量还需要另一个维度的检查。准确、完整、一致、精确和有用，属于可检查的功能质量；流畅、贴合人的需要、能预判用户下一步，则属于更深层的使用质量。Diátaxis 主要帮助文档贴近用户需求、保持阅读路径的流动，并暴露内容混杂造成的缺口。它不能替代技术审校、版本测试、信息设计和视觉设计。

因此，文档改造的优先顺序可以是：先保证事实正确，再按用户意图拆分内容，接着修正标题和链接，最后通过真实用户任务检查阅读流程。四类文档无需在发布前填满，它们用于持续判断内容归属和下一步改动。

结语

Diátaxis 提供了一种稳定的文档决策方式：先确认读者处于学习还是工作，再确认他需要行动指导还是概念认知。教程、操作指南、参考和解释由此各自承担清晰任务，文档之间用链接形成完整路径。

对于 API 和 DevOps 项目，最先能产生收益的动作通常很小：把一段混杂的内容拆成两个意图明确的页面，给参数补上参考条目，或者在教程中增加一个可见的成功结果。持续完成这样的局部改进，文档结构会随着内容质量一起形成。

来源：

• Diátaxis 官方网站
• Start here: Diátaxis in five minutes
• The compass
• Diátaxis as a guide to work
• Towards a theory of quality in documentation