# 组织文档的 Diátaxis 框架

LLMS 索引： [llms.txt](/llms.txt)

---

Diátaxis 框架旨在解决文档混乱导致信息无从查找的问题。这个框架把文档分为四个类型：

- 教程（Tutorials）- 学习导向：面向完全新手，从 0 开始，一步一步完成一个具体任务（例子：如何创建第一个接口）
- 操作指南（How-to Guides）- 任务导向：面向已有一些基础知识和经验的用户，达成某个特定目标，步骤清晰但是不过度详细（例子：如何排查接口的高耗时问题）
- 解释说明（Explanation）- 理解导向：提供背景和上下文，解释怎么做背后的“为什么”，帮助建立心智模型（例子：框架处理请求的完整流程）
- 参考文档（Reference）- 信息导向：提供完整准确的技术细节（例子：运行时配置参数列表）


其中 “教程” 和 “操作指南” 都是行动导向的，可能容易混淆；在另一篇文章中详细指出了这两者的不同：
- 教程：帮助学习者获得基础技能（**学习**），在人工设计的环境中提供安全的学习体验，没有意外情况，出错的责任在文档作者
- 操作指南：帮助已经掌握技能的用户完成具体任务（**工作**），在现实环境中进行，提供步骤但也能灵活应对现实情况（if X then Y），出错的责任在用户自己

src: https://diataxis.fr/start-here/

diff: https://diataxis.fr/tutorials-how-to/#tutorials-how-to

via: https://github.blog/developer-skills/documentation-done-right-a-developers-guide/