diataxis

Diátaxis 文档框架

应用 Diátaxis 系统化框架来组织和编写文档。

四种文档类型

Diátaxis 依据两个维度，明确划分为四种类型：

	获取（学习）	应用（工作）
行动（实践）	教程	操作指南
认知（思考）	解释	参考

1. 教程——以学习为导向

将教程写成课程。手把手带领学习者完成实践体验，让他们通过动手操作来掌握技能。

• 使用第一人称复数（“我们将……”）
• 开篇就展示学习者将要达成的目标
• 尽早且频繁地呈现可见成果
• 严格限制解释内容——改为链接到相关说明
• 聚焦具体内容，不涉及选项和替代方案
• 力求绝对可靠

加载 references/tutorials.md 查看完整指南。

2. 操作指南——以目标为导向

将操作指南写成实用指引，帮助已有相应能力的用户实现具体的现实目标。

• 清楚命名：“如何 [实现 X]”
• 使用条件式祈使句（“如果你想要 x，就执行 y”）
• 假定用户具备相应能力——不要从头教学
• 省略非必要内容；实用性优先于完整性
• 允许用户灵活选择替代方案

加载 references/how-to-guides.md 查看完整指南。

3. 参考——以信息为导向

将参考文档写成对系统机制的技术描述。保持简洁、权威，以供查阅，而非通读。

• 只做描述——语气保持中立
• 采用标准且一致的模式
• 与产品结构保持对应
• 提供示例以作说明，而非解释

加载 references/reference.md 查看完整指南。

4. 解释——以理解为导向

将解释写成深入探讨，帮助读者加深理解。回答“能给我介绍一下……吗？”

• 与相关主题建立联系
• 提供背景：说明事物为何如此
• 围绕主题展开（标题：“关于 X”）
• 坦诚表达观点和视角
• 严格限定范围——不要吸收其他类型的内容

加载 references/explanation.md 查看完整指南。

指南针——不确定时

提出两个问题来判断内容类型：

1. 行动还是认知？ 内容是关于实践还是思考？
2. 获取还是应用？ 内容用于学习还是工作？

两者的交叉点决定你正在编写的类型。加载 references/compass.md 查看详细的判断指南。

如何应用

1. 对内容分类——使用上面的指南针问题。
2. 检查是否混合类型——这部分内容是否试图同时完成两件事？
3. 拆分混合内容——从教程中抽出解释，从参考文档中抽出说明。
4. 应用相应类型的原则——遵循上面该类型的要点。
5. 在不同类型之间建立链接——不要嵌入内容，而要相互引用。

不要创建空的四节结构，再试图往里面填内容。应让结构从内容中自然形成。

示例

用户提出：“为我们的 CLI 工具编写一份入门指南。”

1. 分类：“入门”意味着用户通过实践来学习 → 教程。
2. 检查：这不是操作指南——用户不是在解决某个具体问题，而是在熟悉工具。
3. 应用教程原则：
   • 开篇说明他们将构建什么：“在本教程中，我们将安装 CLI 并部署一个示例应用。”
   • 通过具体步骤逐步引导，在每个阶段展示可见成果。
   • 尽量减少解释：“我们使用 --verbose 来显示更多输出”，而不是用一段话介绍日志级别。
   • 将标志详情链接到参考文档，将架构说明链接到解释文档。
4. 结果：一堂聚焦的课程，而不是伪装成教程的功能巡览。

常见错误

错误	失败原因	修正方法
解释一切的教程	解释会打断学习流程，导致学习者分心	将解释移至单独的文档，并添加链接
教授基础知识的操作指南	有能力的用户不需要入门指导，这会浪费他们的时间	默认用户具备相应能力，或拆分为教程和操作指南
带有观点和建议的参考文档	查阅参考文档的用户需要的是事实，而不是指导	将建议移至解释文档
在参考文档中混入解释	两者都会被削弱：参考文档变得冗长，解释也无法充分展开	拆分为独立文档
实际上是功能概览的“快速入门”	没有学习目标，也没有连贯的过程，用户无法掌握技能	选定用户要完成的一件事，并围绕它展开
创建空的教程／操作指南／参考／解释章节	没有内容的结构只是无用的脚手架	先撰写内容，再让结构自然形成

关键规则

• 绝不混合类型。 每种类型都有自己的目的、语气和形式。
• 用户所处的模式很重要。 学习与工作是根本区别。教程和解释服务于学习；操作指南和参考服务于工作。
• 在不同类型之间建立链接， 不要将一种类型嵌入另一种类型。

深入了解

需要详细指导时，按需加载参考文件：

主题	文件
撰写教程	references/tutorials.md
撰写操作指南	references/how-to-guides.md
撰写参考文档	references/reference.md
撰写解释文档	references/explanation.md
罗盘决策工具	references/compass.md
教程与操作指南的区别	references/tutorials-how-to.md
参考与解释的区别	references/reference-explanation.md
工作流方法论	references/how-to-use-diataxis.md
Diátaxis 为何有效（基础原理）	references/foundations.md
二维地图	references/map.md
文档质量	references/quality.md
复杂层级结构	references/complex-hierarchies.md