文档类型：教程、操作指南、参考和解释

使用 Diátaxis 框架为每个页面选择合适的文档类型：教程、操作指南、参考和解释。

并非所有文档都服务于相同的目的。一个引导新用户完成首次部署的教程，与开发人员每天查阅的 API 参考，有着根本性的不同。将这些目的混合在一个页面中会创建出两个目标都无法很好实现的内容。

Diátaxis 框架提供了一个实用的系统，根据用户当下的需求对文档进行分类。

​

四种文档类型

​

教程（以学习为导向）

教程通过实践来教学。用户的目标是学习新东西，而教程的目标是给他们一次成功的体验——而不是记录每个选项或解释每个细节。

一个好的教程：

• 不假设用户对特定任务有任何先验知识
• 带领用户从头到尾完成一个完整的、可运行的示例
• 最小化选择——告诉用户确切该做什么，而不是提供替代方案
• 在有意义的里程碑处标记进度（“你现在已经配置好了身份验证”）
• 只解释足够让用户继续前进的内容，而不是所有需要知道的东西

教程是编写和维护投入最大的内容类型，但它们对新用户能否成功使用你的产品有着巨大的影响。

​

操作指南（以任务为导向）

操作指南帮助用户完成特定目标。与教程不同，它们假设用户已经有一些背景知识，想要完成某件特定的事情，而不是学习一个概念。

一个好的操作指南：

• 在标题和全文中针对一个特定任务
• 假设用户已了解先决条件
• 提供清晰的步骤序列，不包含不必要的背景信息
• 描述该做什么，而不是系统底层如何运作

教程和操作指南的区别在实践中很重要：一个关于”身份验证入门”的教程会一步一步地引导新用户完成整个过程。一个关于”轮换你的 API 密钥”的操作指南则假设用户知道什么是 API 密钥，只需要操作步骤。

​

参考（以信息为导向）

参考文档准确、完整地描述系统。用户查阅它是为了查找某些内容——他们不是在顺序阅读，也不是在学习。

好的参考文档：

• 将完整性和准确性置于一切之上
• 易于扫描：表格、一致的格式、简短的描述
• 避免解释性或概念性内容
• 记录所有内容，包括默认值、限制和边缘情况
• 紧贴所记录事物的结构（API 参考遵循 API 的结构）

API 参考、配置选项列表和 CLI 命令参考都是参考内容。

​

解释（以理解为导向）

解释加深对概念的理解。用户阅读它们是因为想要理解某些东西为什么以这种方式运作，而不是如何执行特定任务。

好的解释内容：

• 阐述设计决策背后的背景和动机
• 承认权衡和替代方案
• 在更广泛的系统中连接各个概念
• 在适当的时候敢于表达观点

架构概述、概念指南和”X 如何运作”页面都是解释内容。它们与操作指南的区别在于，读完一篇解释文章的读者不应该觉得被告知要做某事——而应该觉得自己更好地理解了某事。

​

为每个页面选择合适的类型

问题	教程	操作指南	参考	解释
用户的目标是什么？	通过实践学习	解决特定问题	查找精确信息	理解一个概念
用户的知识水平如何？	初学者	中级	有经验	任何水平
内容是否以任务为导向？	是，有引导的	是，特定的	否	否
是否是顺序性的？	是	通常是	否	否

当你不确定某个页面适合哪种类型时，问一下：“用户读完这个之后会做什么？“如果他们完成了一个任务，那就是操作指南或教程。如果他们现在理解了某些东西并可能去其他地方采取行动，那就是解释。如果他们查找了一个特定的细节，那就是参考。

​

为每种类型写作

​

编写教程

在开头设定期望：用户在结束时将构建或完成什么？使用 <Steps> 组件来展示顺序进度，并在自然的里程碑处庆祝完成。最小化决策——在有多种有效方法的地方，选择一种并明确说明。

​

编写操作指南

在标题中以任务开头：“如何配置 webhooks”、“如何从 v1 迁移到 v2”。从用户的角度而非产品的角度来写。跳过不影响步骤的背景信息。为想要了解更多的用户链接到解释或参考内容。

​

编写参考

围绕所描述的事物来组织参考文档，而不是围绕用户旅程。在所有条目中使用一致的格式。每个参数、标志或选项都应该有类型、默认值和一行描述。保持易于扫描。

​

编写解释

从你要回答的问题开始：“为什么身份验证以这种方式运作？“或”组织和工作区之间有什么区别？“承认存在多种方法，并解释产品为什么做出这样的选择。为想要将所学付诸行动的用户链接到操作指南。

​

保持类型一致性的技巧

• 在写作前分配内容类型。 提前决定会影响所有其他写作决策——结构、长度、语气、包含什么和排除什么。
• 审查混合用途的页面。 同时解释一个概念、包含一个教程并引用一个选项列表的页面难以维护也难以使用。将它们拆分或选择一个主要类型。
• 根据你的产品调整框架。 Diátaxis 是一个起点，而不是一个严格的规则。具有特殊结构的产品可能需要混合方法。其底层原则——将内容与用户当下的需求相匹配——具有普遍适用性。

​

常见问题

我是否需要为每个功能都准备四种内容类型？

不需要。小功能可能只需要一个操作指南和一个参考条目。这些类型描述的是用户可能有的需求，而不是你必须完成的清单。从你的用户实际需要的内容开始——通常是操作指南和参考——然后在用户持续难以入门或理解某些内容的地方添加教程和解释。

教程和操作指南之间有什么区别？

教程是学习体验。用户从没有知识开始，到最终构建或完成了某些东西，教程承担了大部分教学工作。操作指南是任务参考。用户知道他们想做什么，需要的是执行步骤。一个关于”构建你的第一个集成”的教程和一个关于”连接新集成”的操作指南可能涵盖类似的操作，但服务于完全不同背景下的完全不同的用户。

一个页面能否服务于多种内容类型？

在实践中，页面经常混合类型——尤其是将教程和操作指南融合在一起的入门内容。问题在于这种混合是服务于用户还是让他们困惑。如果一个页面既需要教授一个概念（解释）又需要引导完成设置（教程），清晰的章节结构可以奏效。如果内容混合得太多以至于无法清晰地组织，将其拆分为单独的页面通常会产生更好的结果。

参考文档应该有多详细？

足够全面，使用户无需阅读源代码或联系支持团队就能理解某个参数或选项。每个可配置的值都应该有描述、类型、默认值和示例。省略边缘情况或限制的参考文档迫使用户通过反复试错来发现这些限制——这是文档的失败，而不是用户的错误。

​

相关页面

内容模板

复制和修改每种内容类型的模板。

风格与语气

以一致的风格编写有效的文档。

了解你的受众

研究和定义你的文档受众。

导航

有效地组织你的文档结构。

改进你的文档

使用数据和指标来改进文档。