Back to Details

diataxis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Diátaxis Documentation Framework

Diátaxis文档框架

Apply the Diátaxis systematic framework to structure and write documentation.
应用Diátaxis系统化框架来构建和编写文档。

The Four Documentation Types

四类文档类型

Diátaxis identifies exactly four types, defined by two axes:
Acquisition (study)Application (work)
Action (doing)TutorialHow-to guide
Cognition (thinking)ExplanationReference
Diátaxis明确界定了四类文档，由两个维度划分：
学习获取实际应用
行动实践教程操作指南
认知理解说明文档参考文档

1. Tutorials — learning-oriented

1. 教程 — 以学习为导向

Write tutorials as lessons. Take the learner by the hand through a practical experience where they acquire skills by doing.
  • Use first-person plural ("We will...")
  • Show where they're going up front
  • Deliver visible results early and often
  • Ruthlessly minimize explanation — link to it instead
  • Focus on the concrete, ignore options and alternatives
  • Aspire to perfect reliability
Load 
references/tutorials.md
for full guidance.
将教程编写成课程形式。带领学习者通过实践操作，在动手过程中掌握技能。
  • 使用第一人称复数（“我们将……”）
  • 提前告知学习者最终目标
  • 尽早且频繁地展示可见成果
  • 尽量减少解释内容，改用链接跳转至相关说明
  • 聚焦具体操作，忽略可选方案和替代方法
  • 追求流程的绝对可靠性
加载
references/tutorials.md
获取完整指导。

2. How-to guides — goal-oriented

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

Write how-to guides as practical directions for an already-competent user to achieve a specific real-world goal.
  • Name clearly: "How to [achieve X]"
  • Use conditional imperatives ("If you want x, do y")
  • Assume competence — don't teach
  • Omit the unnecessary; practical usability > completeness
  • Allow flexibility with alternatives
Load 
references/how-to-guides.md
for full guidance.
为已具备基础能力的用户编写操作指南，提供实现特定实际目标的实用步骤。
  • 命名清晰：“如何[实现X目标]”
  • 使用条件祈使句（“若你需要X，请执行Y”）
  • 假设用户具备基础能力，无需从零教学
  • 省略无关内容，优先保证实用性而非完整性
  • 允许提供灵活的替代方案
加载
references/how-to-guides.md
获取完整指导。

3. Reference — information-oriented

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

Write reference as technical description of the machinery. Keep it austere, authoritative, consulted not read.
  • Describe and only describe — neutral tone
  • Adopt standard, consistent patterns
  • Mirror the structure of the product
  • Provide examples to illustrate, not explain
Load 
references/reference.md
for full guidance.
编写参考文档时，聚焦于对产品机制的技术描述。保持内容简洁、权威，供用户查阅而非通读。
  • 仅做描述，保持中立语气
  • 采用标准、一致的格式
  • 与产品结构保持一致
  • 提供示例用于说明，而非解释
加载
references/reference.md
获取完整指导。

4. Explanation — understanding-oriented

4. 说明文档 — 以理解为导向

Write explanation as discursive treatment that deepens understanding. Answer "Can you tell me about...?"
  • Make connections to related topics
  • Provide context: why things are so
  • Talk about the subject (title: "About X")
  • Admit opinion and perspective
  • Keep closely bounded — don't absorb other types
Load 
references/explanation.md
for full guidance.
说明文档采用论述式写法，帮助用户深化对内容的理解。用于回答“能否介绍一下……？”这类问题。
  • 建立与相关主题的关联
  • 提供背景信息：解释事物为何如此设计
  • 围绕主题展开（标题：“关于X”）
  • 可融入观点和视角
  • 内容聚焦，避免涵盖其他类型文档的内容
加载
references/explanation.md
获取完整指导。

The Compass — When In Doubt

判断罗盘 — 存疑时使用

Ask two questions to classify content:
  1. Action or cognition? Is this about doing, or thinking?
  2. Acquisition or application? Is this for learning, or for working?
The intersection tells you which type you're writing. Load 
references/compass.md
for detailed decision guidance.
通过两个问题对内容进行分类：
  1. 行动实践还是认知理解？ 内容是关于动手操作，还是知识理解？
  2. 学习获取还是实际应用？ 内容是用于学习，还是用于工作场景？
两个问题的交叉结果即为文档所属类型。加载
references/compass.md
获取详细的决策指导。

How To Apply

应用步骤

  1. Classify the content — use the compass questions above.
  2. Check for type mixing — does this piece try to do two things at once?
  3. Separate mixed content — pull explanation out of tutorials, pull instructions out of reference.
  4. Apply the type's principles — follow the bullet points for that type above.
  5. Link between types — don't embed, cross-reference instead.
Do NOT create empty four-section structures and try to fill them. Let structure emerge from content.
  1. 分类内容 — 使用上述的罗盘问题进行判断。
  2. 检查类型混合情况 — 这份文档是否试图同时实现两种目标？
  3. 拆分混合内容 — 将说明内容从教程中剥离，将操作步骤从参考文档中移出。
  4. 应用对应类型的原则 — 遵循上述对应文档类型的要点。
  5. 跨类型链接 — 不要嵌入内容，而是采用交叉引用的方式。
切勿先创建空的四部分结构再填充内容。应让结构从内容中自然衍生。

Example

示例

User asks: "Write a getting-started guide for our CLI tool."
  1. Classify: "Getting started" = the user is learning, by doing → Tutorial.
  2. Check: Not a how-to guide — the user isn't solving a specific problem, they're acquiring familiarity.
  3. Apply tutorial principles:
    • Open with what they'll build: "In this tutorial, we will install the CLI and deploy a sample app."
    • Lead through concrete steps with visible results at each stage.
    • Minimize explanation: "We use 
      --verbose
      for more output" not a paragraph on logging levels.
    • Link to reference for flag details, link to explanation for architecture.
  4. Result: A focused lesson, not a feature tour disguised as a tutorial.
用户需求：“为我们的CLI工具编写一份入门指南。”
  1. 分类：“入门”意味着用户通过动手操作进行学习 → 教程。
  2. 检查：这不是操作指南 — 用户并非在解决特定问题，而是在熟悉工具。
  3. 应用教程原则：
    • 开篇说明成果：“在本教程中，我们将安装CLI工具并部署一个示例应用。”
    • 引导用户完成具体步骤，每个阶段都展示可见成果。
    • 尽量减少解释：只需说明“我们使用
      --verbose
      参数获取更多输出”，无需用段落解释日志级别。
    • 链接至参考文档查看参数详情，链接至说明文档了解架构信息。
  4. 成果：一份聚焦的课程，而非伪装成教程的功能介绍。

Common Mistakes

常见错误

MistakeWhy it failsFix
Tutorial that explains everythingExplanation breaks the learning flow — learner loses focusMove explanation to a separate doc, link to it
How-to guide that teaches basicsCompetent users don't need onboarding — it wastes their timeAssume competence, or split into tutorial + how-to
Reference with opinions and adviceUsers consulting reference need facts, not guidanceMove advice to explanation
Explanation mixed into referenceDilutes both — reference becomes verbose, explanation can't developSeparate into distinct documents
"Getting started" that's actually a feature tourNo learning goal, no coherent journey — user doesn't acquire skillPick one thing the user will accomplish, build toward it
Creating empty Tutorials/How-to/Reference/Explanation sectionsStructure without content is useless scaffoldingWrite content first, let structure emerge
错误失败原因修复方案
教程中包含大量解释内容解释会打断学习流程，分散学习者注意力将解释内容移至单独文档，通过链接跳转
操作指南中教授基础知识目标用户已具备基础能力，基础知识讲解会浪费他们的时间假设用户有基础，或拆分为教程+操作指南
参考文档中包含观点和建议用户查阅参考文档是为了获取事实，而非指导将建议内容移至说明文档
参考文档中混入说明内容会同时削弱两类文档的价值 — 参考文档变得冗长，说明内容无法充分展开拆分为独立的文档
“入门指南”实际是功能介绍没有明确的学习目标和连贯的学习路径，用户无法真正掌握技能选定一个用户可完成的具体目标，围绕其展开内容
先创建空的“教程/操作指南/参考文档/说明文档”板块无内容支撑的结构只是无用的框架先编写内容，让结构自然衍生

Critical Rules

核心规则

  • Never mix types. Each type has its own purpose, tone, and form.
  • The user's mode matters. Study vs. work is the fundamental distinction. Tutorials and explanation serve study. How-to guides and reference serve work.
  • Link between types rather than embedding one inside another.
  • 切勿混合文档类型。每种类型都有其独特的目的、语气和形式。
  • 用户的使用场景至关重要。学习与工作是核心区别。教程和说明文档服务于学习场景，操作指南和参考文档服务于工作场景。
  • 采用跨类型链接，而非将一种类型的内容嵌入另一种。

Deep Dives

深度拓展

Load reference files on demand for detailed guidance:
TopicFile
Writing tutorials
references/tutorials.md
Writing how-to guides
references/how-to-guides.md
Writing reference docs
references/reference.md
Writing explanation
references/explanation.md
The compass decision tool
references/compass.md
Tutorials vs how-to distinction
references/tutorials-how-to.md
Reference vs explanation distinction
references/reference-explanation.md
Workflow methodology
references/how-to-use-diataxis.md
Why Diátaxis works (foundations)
references/foundations.md
The two-dimensional map
references/map.md
Quality in documentation
references/quality.md
Complex hierarchies
references/complex-hierarchies.md
按需加载参考文件获取详细指导：
主题文件
教程编写
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