Diátaxis

在技术领域，代码写得再好，如果文档晦涩难懂、结构混乱，产品的 adoption（采用率）也会大打折扣。Diátaxis 是一套被广泛认可的技术文档写作框架，它不仅仅是一种格式规范，更是一种基于用户心理模型和内容目的的系统性思维方式。

Diátaxis 核心理念在于：用户在不同的场景下有不同的需求，而文档必须针对这些需求提供特定形式的内容。它将技术文档划分为四个清晰的象限：教程 (Tutorials)、操作指南 (How-to Guides)、技术参考 (Reference) 和 解释说明 (Explanation)。

Diátaxis 四大文档类型详解

Diátaxis 通过两个维度来区分这四种类型：

1. 用户导向：是面向学习（Learning）还是面向工作（Working）？
2. 内容性质：是侧重实践（Practical）还是侧重理论（Theoretical）？

1. 教程 (Tutorials)

• 定位：学习 + 实践。
• 目标：让新手通过亲身体验获得初步能力和信心。
• 特点：
  • 以结果为导向，步骤固定且经过严格测试。
  • 不要求用户理解背后的原理，只需跟随操作即可成功。
  • 示例：“5 分钟构建你的第一个 Hello World 应用”。
• 关键原则：不要在此处解释“为什么”，只关注“怎么做才能跑通”。

2. 操作指南 (How-to Guides)

• 定位：工作 + 实践。
• 目标：帮助已有基础的用户解决具体的现实问题。
• 特点：
  • 针对特定场景或任务（如“如何配置 SSL 证书”、“如何重置密码”）。
  • 假设用户已具备基本知识，直接给出步骤。
  • 允许用户根据实际情况调整步骤。
• 关键原则：聚焦于达成目标，提供清晰的步骤列表，避免冗长的背景介绍。

3. 技术参考 (Reference)

• 定位：工作 + 理论。
• 目标：提供准确、完整的技术细节描述，供用户查阅。
• 特点：
  • 枯燥但必要，如 API 文档、参数列表、命令行选项。
  • 结构严谨，通常由代码自动生成或严格遵循模板。
  • 不包含操作流程或背景故事。
• 关键原则：准确性高于一切，保持简洁、客观、无歧义。

4. 解释说明 (Explanation)

• 定位：学习 + 理论。
• 目标：帮助用户理解概念、背景、设计决策及生态系统。
• 特点：
  • 探讨“为什么”这样做，而非“怎么做”。
  • 提供上下文、最佳实践、架构理念及与其他技术的对比。
  • 示例：“理解 React 的虚拟 DOM 机制”、“为什么我们选择 Rust 重写核心模块”。
• 关键原则：提供洞察力和背景知识，帮助用户建立心智模型。

为什么选择 Diátaxis？

1. 以用户为中心

传统文档往往以“功能”为中心（例如：“文件菜单”、“设置页面”），而 Diátaxis 以“用户需求”为中心。用户不会想“我要看参考文档”，而是想“我要解决这个问题”或“我要学习这个概念”。Diátaxis 确保用户在正确的时间找到正确的内容。

2. 消除内容混淆

很多文档失败的原因是将四种类型混杂在一起。例如，在教程中插入大量的原理解释，会让新手感到挫败；在参考文档中加入操作步骤，会让查阅者感到烦躁。Diátaxis 强制分离关注点，使每种文档都纯粹且高效。

3. 易于维护与扩展

对于文档维护者而言，Diátaxis 提供了清晰的分类标准。当需要新增内容时，只需判断其属于哪个象限，即可确定其风格、结构和受众。这大大降低了团队协作中的沟通成本。

如何应用 Diátaxis？

1. 审计现有文档：检查当前文档库，识别哪些内容混杂了多种类型。
2. 重新分类：将内容拆解并归入四个象限。例如，将 API 参数说明移入“参考”，将入门步骤移入“教程”，将设计理念移入“解释”。
3. 制定规范：为每种类型制定写作模板和风格指南。
   • 教程：使用第二人称（“你”），步骤编号，确保可复现。
   • 指南：问题导向，步骤清晰，提供故障排除提示。
   • 参考：结构化数据，术语一致，链接相关指南。
   • 解释：叙事性强，图表辅助，链接相关参考和教程。
4. 持续迭代：根据用户反馈和数据（如搜索关键词、页面停留时间）优化各象限内容。

Diátaxis 不仅是一套文档框架，更是一种尊重用户时间与认知负荷的产品哲学。它提醒我们：文档不是代码的附属品，而是产品体验的重要组成部分。

通过清晰区分教程、操作指南、技术参考和解释说明，Diátaxis 帮助团队构建出既适合新手入门、又满足专家查阅的高质量文档体系。无论是开源项目还是企业内部平台，采纳 Diátaxis 都是提升开发者体验（DX）的最有效途径之一。