writing-documentation-with-diataxis

使用 Diataxis 编写文档

你可以使用 Diataxis 框架帮助用户创建和改进技术文档。该框架根据用户需求，将文档分为四种不同类型。

什么是 Diataxis

Diataxis 是一个用于创建使用体验良好的文档的框架——让文档读起来流畅、能预见用户需求，并契合人们实际参与某项实践的方式。

重要提示：Diataxis 是一种方法，而不是模板。不要为了凑齐教程、操作指南、参考资料和解释说明而创建空洞的章节。应创建能满足实际用户需求的内容，应用这些原则，并让结构自然形成。

核心见解：文档服务于某个技能领域的实践者。他们的需求会根据两个维度而变化：

1. 行动 vs 认知——做事 vs 理解事物
2. 习得 vs 应用——学习 vs 工作

这两个维度恰好形成四种文档类型：

• 边做边学 → 教程
• 为达成目标而工作 → 操作指南
• 工作时需要事实信息 → 参考资料
• 通过学习来理解 → 解释说明

为什么恰好是四种：这些并非随意划分的类别。这两个维度恰好形成四个象限，不可能是三个或五个。这完整涵盖了文档必须涉及的内容范围。

Diataxis 指南针（你的主要工具）

不确定需要哪种文档类型时，请问自己两个问题：

1. 内容是为了指导行动还是促进认知？

• 行动：实践步骤、执行操作
• 认知：理论知识、理解事物

2. 内容是为了帮助习得还是应用技能？

• 习得：学习、研习
• 应用：工作、完成任务

然后对照下表：

内容类型	用户活动	文档类型
行动	习得	教程
行动	应用	操作指南
认知	应用	参考资料
认知	习得	解释说明

创建新文档时

1. 确认用户需求

问问自己：

• 用户是谁？（学习者还是实践者）
• 他们需要什么？（做某件事还是理解某件事）
• 他们处于什么情境？（学习还是工作）

2. 使用指南针

运用上述两个问题，判断哪种文档类型能满足这一需求。

3. 应用核心原则

对于教程（通过实践学习）：

• 你要对学习者的成功负责——每一步都必须有效
• 注重实践，而非讲解
• 提前展示学习者将要完成的内容
• 尽早并频繁地呈现可见成果
• 维持对结果的预期（“你将看到……”“注意……”）
• 具体明确——只提供一条路径，不提供替代方案
• 消除意外情况——确保结果完全可重复
• 鼓励重复操作，培养“亲手实践的感觉”
• 力求绝对可靠

对于操作指南（为实现目标而工作）：

• 解决现实问题，而非介绍工具功能
• 假设读者具备相应能力——他们知道自己想要什么
• 按符合人类思维的逻辑顺序展开
• 通过条件说明应对现实世界的复杂性（“如果出现 X，就执行 Y”）
• 保持流程顺畅——预判读者的下一步操作，尽量减少上下文切换
• 省略不必要的细节——实用性比完整性更重要
• 聚焦任务，而非工具
• 清晰命名指南：“如何[实现 X]”

对于参考文档（工作时查阅事实）：

• 描述事实，不提供指示——只呈现中立信息
• 结构应与产品架构相对应
• 全文采用标准且一致的模式
• 严谨、权威，避免歧义
• 将描述与指示分开
• 提供简洁的用法示例
• 完整性至关重要（与操作指南不同）

对于解释文档（理解概念）：

• 从多个角度探讨主题
• 回答“为什么”——设计决策、历史和限制
• 联系相关概念
• 提供背景和全局视角
• 允许表达观点和立场——讨论权衡
• 明确划分内容边界——不包含操作指示或纯参考信息
• 采用更高、更广的视角

4. 使用恰当的语言

教程：“我们将创建……”“首先，执行 X。现在，执行 Y。”“注意……”“你已经构建了……”

操作指南：“本指南将向你展示如何……” “如果你想实现 X，就执行 Y”“要实现 W，就执行 Z”

参考文档：“X 可用作 Y”“子命令包括：A、B、C”“必须使用 X。切勿使用 Y。”

解释文档：“X 的原因是……”“W 比 Z 更好，因为……”“有些人更喜欢 W。这可能有效，但……”

5. 检查内容边界

审阅你的内容：

• 是否有部分内容服务于不同的用户需求？
• 教程中是否包含解释内容？（将其提取出来并添加链接）
• 是否在参考文档中提供了操作指示？（移至操作指南）
• 操作指南中是否包含参考细节？（改为链接至参考文档）

如果内容服务于多种需求，请将其拆分，并在文档之间添加链接。

审阅现有文档时

采用以下迭代流程：

1. 选择一段内容——可以是任意页面、章节或段落

2. 用以下问题审视它：

• 它服务于什么用户需求？
• 它应该属于哪种文档类型？
• 它是否很好地满足了该需求？
• 使用的语言是否适合这种类型？
• 是否有内容应归入其他类型？

3. 如果不确定类型，就使用指南针

4. 找出一项眼下有帮助的改进

5. 根据 Diataxis 原则进行改进

6. 对另一段内容重复以上步骤

不要试图一次性重构所有内容。通过改进单个内容，逐步形成整体结构。

核心原则

流畅性至关重要：文档应随着用户的思路顺畅展开，预判他们接下来需要什么。尤其是编写操作指南时，请思考：他们需要牢记什么？何时能解答这些疑问？接下来他们会需要什么？

明确界限有助于保护内容：将不同类型的文档分开。最常见的错误是把教程（学习）和操作指南（做事）混在一起。

结构应服从内容：不要创建空洞的章节。编写能满足实际需求的内容，运用 Diataxis 原则，让结构自然呈现。

一次满足一个需求：每份内容只服务于一种用户需求。如果用户有多种需求，就创建多份内容，并在它们之间添加链接。

好的文档读起来令人愉悦：除了准确之外，文档还应预判用户需求、行文流畅，并符合人们的工作方式。

应避免的常见错误

1. 混淆教程和操作指南——教程用于学习（研习），操作指南用于做事。出现以下情况，说明你可能把两者混在了一起：

   • 你的“教程”默认用户已知道自己想做什么
   • 你的“教程”提供了多种做法
   • 你的“操作指南”试图讲解基础概念
   • 你的“教程”涉及现实世界中的复杂情况

2. 教程中过度解释——相信学习会在实践中发生。只做最简要的解释，并链接到其他地方的详细说明。

3. 试图讲授知识的操作指南——假设用户具备相应能力，不要解释基础知识。

4. 包含操作指示的参考资料——参考资料用于描述，而不是告诉用户该做什么。

5. 面向行动的文档中包含解释性内容——将其移至解释型文档，并添加链接。

快速参考表

方面	教程	操作指南	参考资料	解释型文档
回答的问题	“能教教我吗？”	“我该如何……？”	“……是什么？”	“为什么……？”
用户状态	通过实践学习	正在执行任务	正在工作，需要事实	正在研习以求理解
内容	操作步骤	操作步骤	信息	信息
形式	一堂课	指引	描述	讨论
责任归属	教师负责	用户负责	中立	共同承担
语气	支持、引导	直接、有条件	简洁、客观	探讨性、重视语境

配套文件

如需更详细的指导，请参阅：

• principles.md——每种文档类型的完整原则及示例
• reference.md——质量框架、复杂场景和补充指导

输出要求

应用 Diataxis 时：

• 直接、务实
• 专注于满足用户需求
• 使用指南针来消除疑虑
• 说明你采用了哪种文档类型，以及原因
• 如果审阅文档，请具体说明它应属于哪种类型，以及如何改进
• 全文使用英式英语拼写