你的项目文档是不是也这样：写的时候很爽，用的时候找不到；README 又长又杂，API 文档没有示例，教程和参考混在一起，新人看完还是不会用？
如果答案是「是」，那你需要了解一下 Diátaxis——一套被 Cloudflare、Gatsby、Vonage 等大量技术团队用来重构文档的系统化框架。这个词来自古希腊语（dia "across" + taxis "arrangement"），意思是「跨越式组织」，它解决的问题正是：文档应该写什么、怎么写、怎么组织。
一句话理解：Diátaxis 把技术文档分成四种类型——Tutorial（教程）、How-to guide（操作指南）、Reference（参考资料）、Explanation（概念解释）。每种类型对应读者的一种特定需求，四者缺一不可、不可混淆。
一、为什么要关心文档架构？
大多数团队的文档问题不是「写得不够多」，而是四种内容混在一起。最常见的失败模式：
- README 膨胀症——安装、快速开始、完整 API、设计理念全塞在一个页面，越来越长，谁也不想看
- 教程和参考混淆——把 API 文档写成「跟着我一步步做」，用户想查参数时找不到；或者把参考手册写成教程，新人根本读不下去
- 没有概念解释——文档默认读者已经理解领域背景，新手上来就懵
- 维护者无法判断内容该放哪——新内容写到一半不知道属于哪个栏目，最后随便塞
Diátaxis 的价值在于：它给内容一个明确的「归属判断」，让写的人和读的人都舒服。它很轻量——不强制任何实现方式，不绑定工具链，任何团队都可以立刻开始应用。
二、四象限：一张图看懂 Diátaxis
Diátaxis 的核心是一个 2×2 矩阵，由两个维度构成：
- 用户需求维度：学习（learning）vs 执行（doing）——读者是想「学会」还是想「完成任务」？
- 内容性质维度：实践（practical）vs 理论（theoretical）——内容偏「操作步骤」还是偏「知识概念」？
| 面向学习（Learn） | 面向执行（Do） | |
|---|---|---|
| 实践导向 | ✅ Tutorial（教程） | ✅ How-to guide（操作指南） |
| 理论导向 | ✅ Explanation（概念解释） | ✅ Reference（参考资料） |
1. Tutorial —— 教程（学习 + 实践）
目标是让读者从零学会。特点：循序渐进、有成果（做完有成就感）、不追求覆盖全部功能。它是「跟着做就能学会」的路径。
2. How-to guide —— 操作指南（执行 + 实践）
目标是帮读者完成任务。特点：面向具体问题（「如何配置 HTTPS」「如何迁移数据库」）、步骤清晰、可复制。它不教原理，只给答案。
3. Reference —— 参考资料（执行 + 理论）
目标是精确描述。特点：客观、完整、格式化（API 参数表、CLI 选项、配置字段）。它不做解释、不引导，只提供权威事实。
4. Explanation —— 概念解释（学习 + 理论）
目标是建立理解。特点：讲「为什么」、讲背景、讲设计决策、讲权衡。它不教操作，只建立心智模型。
最常见的误区：把四种内容混写。比如在 Reference 里加「建议你先看看这个教程」，在 How-to 里解释底层原理——这样每种内容的读者都会被干扰。Diátaxis 的原则是：每种内容各归其位，互相链接而不是互相混入。
三、用「用户意图」判断内容归属
判断一段新内容该放哪，可以问一个问题：读者此刻想做什么？
| 读者意图 | 应该写 | 典型场景 |
|---|---|---|
| 「我想学会这个工具」 | Tutorial | 新手第一次接触产品 |
| 「我想解决某个具体问题」 | How-to guide | 遇到报错、要配置某项功能 |
| 「我想查某个参数的准确含义」 | Reference | 集成开发、调试、查配置项 |
| 「我想理解为什么这样设计」 | Explanation | 评估选型、深入理解、面试准备 |
这个判断方法也解决了维护者的难题：内容该放哪，不再是个人偏好，而是由读者需求决定。
四、实战：如何用 Diátaxis 重构你的文档
不需要推倒重来，按下面 5 步渐进式应用：
Step 1：盘点现有内容
把现有文档列个清单，按四象限分类。你会发现大部分内容其实散落在错误的位置——先标记出来，不用马上搬。
Step 2：确立导航结构
在文档站导航里建立四个清晰入口：Tutorials / How-to guides / Reference / Explanation。哪怕内容还是旧的，先让结构对。
Step 3：从最高频内容开始迁移
优先迁移用户问得最多的内容。比如把 README 里的「快速开始」提炼成 Tutorial，把「配置项」抽出来变成 Reference 表格。
Step 4：写新内容时先定类型
立一条团队规则：写任何新文档前，先确定它是四类中的哪一类，并遵守该类的内容规范（教程要可跟随、指南要对症、参考要精确、解释要有深度）。
Step 5：用交叉链接代替混写
内容之间用链接串联，而不是互相复制。例如：How-to guide 里链到相关 Reference 和 Explanation，Tutorial 末尾链到进阶 How-to。
💡 判断清单（写之前问自己）
读者想学习 → Tutorial（按步骤、有成果）
读者想做事 → How-to guide（对症、可复制）
读者想查证 → Reference（精确、完整、格式化）
读者想理解 → Explanation（讲为什么、讲权衡）
五、真实案例：大厂怎么用
Diátaxis 不是纸上谈兵，它已经在大量生产环境里被验证：
- Cloudflare——开发者文档以 Diátaxis 作为信息架构的「北极星」，遇到「不知道内容放哪」时用它做决策依据
- Gatsby——开源文档团队用四象限重新组织全部文档，优先服务「用户在不同阶段的目标」
- Vonage——内部文档团队用 Diátaxis 构建了「用户喜欢、贡献者也喜欢维护」的高质量文档体系
它们的共同反馈是：Diátaxis 带来的不只是更清晰的导航，更是文档质量的主动原则——维护者随时可以判断一段内容写得好不好、该不该存在。
六、四象限内容速查表
| Tutorial 教程 | How-to 指南 | Reference 参考 | Explanation 解释 | |
|---|---|---|---|---|
| 读者目标 | 学习 | 完成任务 | 查证事实 | 理解原理 |
| 内容基调 | 循循善诱 | 直接解决问题 | 客观中立 | 深入剖析 |
| 典型形式 | 分步教学、动手项目 | 步骤清单、配置示例 | 参数表、API 文档、CLI 参考 | 博客式长文、设计文档 |
| 判断标准 | 读者学完后会用吗？ | 能照着完成任务吗？ | 信息准确完整吗？ | 读者理解「为什么」了吗？ |
| 常见错误 | 步骤跳跃、没有成果 | 讲原理不讲步骤 | 不完整、夹杂教程 | 只列事实不解释 |
七、常见问题 FAQ
Q：Diátaxis 和普通的「文档分类」有什么区别？
普通的分类（如「指南」「手册」）是凭感觉的标签；Diátaxis 是从读者需求推导出来的系统：两个维度（学习 vs 执行、实践 vs 理论）交叉出四种不可互相替代的内容类型。它给了内容一个可推理的归属逻辑。
Q：一定要四个栏目齐全吗？
不一定。小型项目可能只需要 Tutorial + Reference；但一旦内容多起来，四象限能防止文档膨胀和无序。建议最少保持「教程 / 参考」两个入口，再按需补充。
Q：README 该放哪类？
README 通常是「门面」，不属于四象限中的任何一类——它负责引导读者去正确的象限。理想的 README 很简短：项目是什么 + 一段 Tutorial 入口 + 几个常用链接。
Q：Diátaxis 适合 API 文档吗？
非常适合。API 文档天然需要精确的 Reference（端点、参数、错误码），同时需要 How-to（「如何认证」「如何分页」）和 Tutorial（「10 分钟创建第一个应用」），再加 Explanation（「为什么这样设计」）。
Q：如何让团队都遵循这个框架？
三步：① 在文档站建立四象限导航；② 写一份团队的「内容归属判断指南」（本文的表格可直接抄）；③ 在 PR 模板里加一个勾选项：「新文档属于哪个象限？」——从流程上强制判断。
Q：从哪里可以了解更多？
- 官方网站：diataxis.fr（英文，含完整方法论和案例）
- 2026 年技术博客写作指南——内容创作的结构化思路
- Chatwoot 完全指南——一个好文档长什么样
最后的话：Diátaxis 的价值不在理论，而在实践。它可能是你今年能做出的、性价比最高的文档改进——不用改代码、不用买工具，只需要改变组织内容的方式。今天就从「盘点现有文档」开始吧。