#Diátaxis 文档框架

Diátaxis 是 retaintive 文档站的信息架构标准。本文说明我们为什么采用它，以及每种文档类型如何映射到我们的目录结构。适合所有写文档的人——产品、工程、运营。

#核心思想：按读者状态分类，不按功能分类

传统文档按产品功能组织（"Chapter 3: Settings"），读者找不到想要的东西，因为他们是按任务思考的，不是按功能模块。

Diátaxis 改用读者的认知状态作为分类依据：

                   学习 (Acquisition)    工作 (Application)
                  ──────────────────────────────────────────
  实践 (Action)  │  Tutorial             How-to Guide
                 │  "带我走一遍"          "帮我完成这个任务"
                 │
  理论 (Cognition)│  Explanation          Reference
                 │  "告诉我为什么"        "告诉我是什么"

四种类型的关键区别：

#我们的目录 ↔ Diátaxis 映射

#为什么分类很重要：混放的代价

同一篇文档里混入不同类型，读者会迷失：

• 在 Reference（字段定义）里夹杂了 Explanation（为什么这样设计）→ 读者在查阅时被迫阅读背景故事
• 在 Explanation（产品设计）里加入 How-to（实施步骤）→ 读者想理解设计时被任务步骤打断
• 把 Tutorial 和 How-to 混在一起 → 新手没有引导，老手找不到直接答案

规则：一篇文档只回答一种问题。如果发现自己在写"为什么"的同时也在写"怎么做"，拆成两篇。

#快速分类清单

写文档前问自己：

1. 读者是在学习还是在工作？

   • 学习 → Tutorial 或 Explanation（左列）
   • 工作 → How-to 或 Reference（右列）

2. 文档偏实践还是偏理论？

   • 实践 → Tutorial 或 How-to（上行）
   • 理论 → Explanation 或 Reference（下行）

3. 读者会从头读还是跳着查？

   • 从头读 → Tutorial 或 Explanation
   • 跳着查 → How-to 或 Reference

#关联资源

• doc-architect skill（~/.claude/skills/doc-architect/）：AI 用这个 skill 自动分类并决定文件放哪里
• execution-policy.md（.claude/rules/execution-policy.md）：目录放置规则速查表
• Diátaxis 官方网站：完整框架原文