diataxis

Diátaxis

使用 Diátaxis 框架编写和修正文档的运行手册。Diátaxis 将文档划分为四种模式——教程、操作指南、参考、解释——因为它们分别满足四种彼此相反的用户需求。让这一框架发挥作用的核心理念是：

大多数文档问题归根结底只有一种：内容试图同时满足多种需求。将四种模式分开，大多数困惑便会迎刃而解。

Diátaxis 是描述性的，而非规范性的——它是一种理解文档的方式，而不是一套待填写的模板。无需等到理解整个框架后再开始应用：挑选一件小事，对它进行分类、改进、发布，然后重复。

何时应用

在以下情况使用此技能：

• 编写或生成任何类型的新文档（README、API 文档、指南、入门文档、开发者文档）——在动笔之前决定内容需要哪种或哪些模式。
• 页面令人困惑、内容臃肿，或“试图面面俱到”——诊断模式混杂的问题并将其拆分。
• 用户无法入门、无法完成任务、找不到事实，或不理解原因——找出缺失或薄弱的模式。
• 重构或审查现有文档集——采用小步工作流，而不是大规模重写。
• 你不确定某些内容属于教程、操作指南、参考还是解释——使用指南针判断。

对于纯粹的文案修改或润色（在模式本身已经正确的情况下，请使用文案写作技能），或设计、规范、提案类文档，不要使用此技能——这些内容大多属于解释，使用 dev-rfc 或 feature-spec 更合适。

四种模式

每种模式服务于不同情境下的不同用户，内容风格也各不相同。最快的区分方式如下：

模式	服务对象	侧重	类比	回答的问题
教程	正在学习的初学者	学习、研习	教孩子做饭	“带我边做边学”
操作指南	正在工作的用户	目标、任务	菜谱	“如何实现 X？”
参考	正在工作的用户	信息	百科词条	“X 究竟是什么？”
解释	正在研习的用户	理解	一篇介绍烹饪的文章	“X 为什么是这样的？”

其中两种服务于实际步骤（教程、操作指南），另两种服务于理论知识（参考、解释）。其中两种服务于获取技能／研习的人（教程、解释），另两种服务于运用技能／工作的人（操作指南、参考）。

指南针——判断你正在编写什么

如果不确定某段内容属于哪种模式，请回答两个问题。这是主要的判断工具；完整的决策树见 compass-tree.md。

1. 它是为了指导 行动 还是 认知？——实际步骤（动手做）还是理论知识（思考）。 2. 它服务于 获取 还是 应用？——研习（学习）还是工作（运用所学）。

	行动（实际步骤）	认知（理论知识）
获取（研习／学习）	教程	解释
应用（工作／动手做）	操作指南	参考

可以这样理解这项判断：指导行动 + 服务于获取 → 教程；指导行动 + 服务于应用 → 操作指南；指导认知 + 服务于应用 → 参考；指导认知 + 服务于获取 → 解释。 可在任何尺度上运用指南针——整份文档、某个章节，或偏离了正确模式的单个句子。

常见症状

从这里开始。找到对应的情况，打开相应的决策树。严重程度反映了读者当前受影响的程度（参见 symptoms.md）。

症状 / 触发条件	可能的问题	决策树
“为 X 编写文档” / “记录一下这个”——但不清楚要写哪 种 文档	尚未选择模式——先分类	compass-tree
页面臃肿、冗长，或把教学内容、步骤、规范和观点混在一起	类型混杂——一份文档满足两种需求	wrong-type-tree
新手无法入门 · 熟练用户无法完成任务 · 人们找不到事实 · 用户不理解 原因	某个象限缺失或薄弱	gaps-tree
“我们的文档一团乱——我该从哪里开始？”	需要迭代式工作流，而不是重写	restructure-tree

使用方法

1. 对照症状，在上表中找到对应项，然后打开 references/ 中的决策树。对于大型的 现有 文档集，先运行 bash references/queries/scan-docs.sh <docs_root>——它会筛查出显现多种模式信号的页面，帮你确定哪些页面需要用指南针来分类。
2. 用指南针分类——确定内容服务于四种模式中的哪一种。如有疑问，请打开 compass-tree.md。
3. 阅读对应的类型指南——tutorials、how-to-guides、reference 或 explanation——了解如何写好 该 模式的文档，以及其中应避免包含哪些内容。
4. 分小步开展。 遵循 workflow.md：选择一个小目标 → 评估 → 决定下一项行动 → 执行并发布。切勿推倒一切，自上而下地重构。
5. 根据质量标准评估。 使用 quality.md 判断功能质量（准确性、完整性、一致性）和深层质量（使用体验是否良好，是否能预见用户需求）。
6. 审查现有文档集时，使用 assets/templates/report.md 记录审计结果，避免每次都重新讨论相同的缺口。

设置

此技能使用可选的 config.json 来了解文档所在位置以及审计记录的存放位置。首次使用时，如果 docs_root 为空，且你正在审计现有文档集，请通过 AskUserQuestion 询问用户文档目录，然后保存该目录。不配置也能使用此技能——必要时直接询问。切勿因缺少配置而阻塞流程。

注意事项

应用 Diátaxis 时常见的陷阱——先搭建空洞的结构、试图“平衡”四种类型而不是将它们分开、在教程中解释原理——见 gotchas.md。首次重构前请先阅读。

相关技能

• skill-authoring — 编写 Agent Skills；其 SKILL.md 本身就是一个 Diátaxis 问题（导航 + 参考，而非教程）。
• human-copywrite / humanize — 文档确定了正确模式后，用它们精简文字，让行文更自然。
• dev-rfc / feature-spec — 设计文档和规范文档大多属于 解释；当产物是提案而非用户文档时，请使用这些技能。