文档内容类型
使用 Diátaxis 框架为每个页面选择合适的文档类型：教程、操作指南、参考和解释。
并非所有文档都服务于相同的目的。一个引导新用户完成首次部署的教程，与开发人员每天查阅的 API 参考，有着根本性的不同。将这些目的混合在一个页面中会创建出两个目标都无法很好实现的内容。
Diátaxis 框架提供了一个实用的系统，根据用户当下的需求对文档进行分类。
教程通过实践来教学。用户的目标是学习新东西，而教程的目标是给他们一次成功的体验——而不是记录每个选项或解释每个细节。
一个好的教程：
- 不假设用户对特定任务有任何先验知识
- 带领用户从头到尾完成一个完整的、可运行的示例
- 最小化选择——告诉用户确切该做什么，而不是提供替代方案
- 在有意义的里程碑处标记进度（“你现在已经配置好了身份验证”）
- 只解释足够让用户继续前进的内容，而不是所有需要知道的东西
教程是编写和维护投入最大的内容类型，但它们对新用户能否成功使用你的产品有着巨大的影响。
操作指南帮助用户完成特定目标。与教程不同，它们假设用户已经有一些背景知识，想要完成某件特定的事情，而不是学习一个概念。
一个好的操作指南：
- 在标题和全文中针对一个特定任务
- 假设用户已了解先决条件
- 提供清晰的步骤序列，不包含不必要的背景信息
- 描述该做什么，而不是系统底层如何运作
教程和操作指南的区别在实践中很重要：一个关于”身份验证入门”的教程会一步一步地引导新用户完成整个过程。一个关于”轮换你的 API 密钥”的操作指南则假设用户知道什么是 API 密钥，只需要操作步骤。
参考文档准确、完整地描述系统。用户查阅它是为了查找某些内容——他们不是在顺序阅读，也不是在学习。
好的参考文档：
- 将完整性和准确性置于一切之上
- 易于扫描：表格、一致的格式、简短的描述
- 避免解释性或概念性内容
- 记录所有内容，包括默认值、限制和边缘情况
- 紧贴所记录内容的结构（API 参考遵循 API 的结构）
API 参考、配置选项列表和 CLI 命令参考都是参考内容。
解释加深对概念的理解。用户阅读它们是因为想要理解某些东西为什么以这种方式运作，而不是如何执行特定任务。
好的解释内容：
- 阐述设计决策背后的背景和动机
- 承认权衡和替代方案
- 在更广泛的系统中连接各个概念
- 在适当的时候采取有明确立场的观点
架构概述、概念指南和”X 如何运作”页面都是解释内容。它们与操作指南的区别在于，读完一篇解释文章的读者不应该觉得被指示去做某事——而应该觉得自己更好地理解了某事。
| 问题 | 教程 | 操作指南 | 参考 | 解释 |
|---|---|---|---|---|
| 用户的目标是什么？ | 通过实践学习 | 解决特定问题 | 查找精确信息 | 理解一个概念 |
| 用户的知识水平如何？ | 初学者 | 中级 | 有经验 | 任何水平 |
| 内容是否以任务为导向？ | 是，有引导的 | 是，特定的 | 否 | 否 |
| 是否是顺序性的？ | 是 | 通常是 | 否 | 否 |
当你不确定某个页面适合哪种类型时，问一下：“用户读完这个之后会做什么？“如果他们完成了一个任务，那就是操作指南或教程。如果他们现在理解了某些东西并可能去其他地方采取行动，那就是解释。如果他们查找了一个特定的细节，那就是参考。
在开头设定期望：用户在结束时会构建或完成什么？使用 <Steps> 组件来展示顺序进度，并在自然的里程碑处庆祝完成。最小化决策——在有多种有效方法的地方，选择一种并明确说明。
在标题中以任务开头：“如何配置 webhooks”、“如何从 v1 迁移到 v2”。从用户的角度而非产品的角度来写。跳过不影响步骤的背景信息。为想要了解更多的用户链接到解释或参考内容。
围绕你所描述的对象来组织参考文档，而不是围绕用户旅程。在所有条目中使用一致的格式。每个参数、标志或选项都应该有类型、默认值和一行描述。保持易于扫描。
从你要回答的问题开始：“为什么身份验证以这种方式运作？“或”组织和工作区之间有什么区别？“承认存在多种方法，并解释产品为什么做出这样的选择。为想要将所学付诸行动的用户链接到操作指南。
- 在写作前分配内容类型。 提前决定会影响所有其他写作决策——结构、长度、语气、包含什么和排除什么。
- 审查混合用途的页面。 同时解释一个概念、包含一个教程并引用一个选项列表的页面难以维护也难以使用。将它们拆分或选择一个主要类型。
- 根据你的产品调整框架。 Diátaxis 是一个起点，而不是一个严格的规则。具有特殊结构的产品可能需要混合方法。其底层原则——将内容与用户当下的需求相匹配——具有普遍适用性。