> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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 跟踪、改进方案       |
| `ai/factory/`         | How-to      | Agent 工作方式、任务执行规范、文档操作手册     |
| `ai/product/`         | How-to      | AI 工具使用指南、集成路线图              |
| `team-ops/`           | How-to（未发布） | 成员工作流、GitHub 管理、部署流程         |
| `operations/`         | How-to（未发布） | On-call 指南、Lambda 问题 Runbook |

***

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

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

- 在 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 官方网站](https://diataxis.fr/)：完整框架原文