组织文档的 Diátaxis 框架

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/