Diátaxis 文档框架 — 我们的文档组织原则¶

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

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

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

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

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

四种类型的关键区别：

类型	读者在做什么	文档的任务	我们的例子
Tutorial	在学习，跟着做	带着完成一次有收获的练习	暂无（未来：新用户上手引导）
How-to Guide	在工作，解决问题	给出完成具体目标的步骤	Phase 实施方案、Runbook、Agent 操作手册
Reference	在工作，查阅事实	提供准确、完整的技术描述	DynamoDB schema、字段定义、功能地图
Explanation	在学习，想理解	解释背景、原因、设计决策	行业知识、产品定位、架构为什么这样设计

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

目录	Diátaxis 类型	内容特征
`industry-knowledge/`	Explanation	健身房行业背景、电话类型的业务含义
`product-design/`	Explanation	功能规格、产品决策的理由
`system-design/`	Reference	DynamoDB 表结构、前端架构、功能地图
`architecture/`	Reference	跨 repo 数据流、系统全景
`ui-design/`	Reference	色彩规范、UI 组件规格
`improvement-plans/`	How-to	Phase 实施计划、GAP 跟踪、改进方案
`agentic-factory/`	How-to	Agent 工作方式、任务执行规范、文档操作手册
`ai-agent-design/`	How-to	AI 工具使用指南、集成路线图
`team-ops/`	How-to（未发布）	成员工作流、GitHub 管理、部署流程
`callytics-operations/`	How-to（未发布）	On-call 指南、Lambda 问题 Runbook

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

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

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

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

快速分类清单¶

写文档前问自己：

读者是在学习还是在工作？
学习 → Tutorial 或 Explanation（左列）
工作 → How-to 或 Reference（右列）
文档偏实践还是偏理论？
实践 → Tutorial 或 How-to（上行）
理论 → Explanation 或 Reference（下行）
读者会从头读还是跳着查？
从头读 → Tutorial 或 Explanation
跳着查 → How-to 或 Reference

关联资源¶

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