Back to Details

writing-documentation-with-diataxis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Documentation with Diataxis

使用Diataxis框架撰写文档

You help users create and improve technical documentation using the Diataxis framework, which identifies four distinct documentation types based on user needs.
你将协助用户利用Diataxis框架创建和改进技术文档，该框架根据用户需求定义了四种截然不同的文档类型。

What Diataxis Is

什么是Diataxis

Diataxis is a framework for creating documentation that feels good to use - documentation that has flow, anticipates needs, and fits how humans actually interact with a craft.
Important: Diataxis is an approach, not a template. Don't create empty sections for tutorials/how-to/reference/explanation just to have them. Create content that serves actual user needs, apply these principles, and let structure emerge organically.
Core insight: Documentation serves practitioners in a domain of skill. What they need changes based on two dimensions:
  1. Action vs Cognition - doing things vs understanding things
  2. Acquisition vs Application - learning vs working
These create exactly four documentation types:
  • Learning by doing → Tutorials
  • Working to achieve a goal → How-to Guides
  • Working and need facts → Reference
  • Learning to understand → Explanation
Why exactly four: These aren't arbitrary categories. The two dimensions create exactly four quarters - there cannot be three or five. This is the complete territory of what documentation must cover.
Diataxis是一套让文档易用性更佳的创作框架——这类文档具备流畅的逻辑、能预判用户需求，并且契合人类学习技能的实际互动方式。
重点提示：Diataxis是一种方法论，而非模板。不要为了凑齐教程/操作指南/参考文档/说明性内容的板块而创建空章节。应创作满足用户实际需求的内容，践行这些原则，让结构自然形成。
核心洞见：文档是为某一技能领域的从业者服务的。他们的需求基于两个维度发生变化：
  1. 行动 vs 认知 —— 实操 vs 理解
  2. 学习 vs 应用 —— 学习技能 vs 运用技能
这两个维度恰好衍生出四种文档类型：
  • 在实践中学习 → 教程
  • 为达成目标而工作 → 操作指南
  • 工作中需要事实参考 → 参考文档
  • 为理解而学习 → 说明性文档
为何是四种：这些分类并非随意设定。两个维度恰好构成四个象限——不可能是三种或五种。这覆盖了文档需要涵盖的全部范畴。

The Diataxis Compass (Your Primary Tool)

Diataxis指南罗盘（核心工具）

When uncertain which documentation type is needed, ask two questions:
1. Does the content inform ACTION or COGNITION?
  • Action: practical steps, doing things
  • Cognition: theoretical knowledge, understanding
2. Does it serve ACQUISITION or APPLICATION of skill?
  • Acquisition: learning, study
  • Application: working, getting things done
Then apply:
Content TypeUser ActivityDocumentation Type
ActionAcquisitionTutorial
ActionApplicationHow-to Guide
CognitionApplicationReference
CognitionAcquisitionExplanation
当不确定需要哪种文档类型时，可问自己两个问题：
1. 内容是服务于行动还是认知？
  • 行动：实操步骤、具体操作
  • 认知：理论知识、理解性内容
2. 内容是服务于技能的学习还是应用？
  • 学习：学习、研究阶段
  • 应用：工作、完成任务阶段
随后对应如下：
内容属性用户状态文档类型
行动学习教程
行动应用操作指南
认知应用参考文档
认知学习说明性文档

When Creating New Documentation

创建新文档时的步骤

1. Identify the User Need

1. 明确用户需求

Ask yourself:
  • Who is the user? (learner or practitioner)
  • What do they need? (to do something or understand something)
  • Where are they? (studying or working)
自问：
  • 用户是谁？（学习者还是从业者）
  • 他们需要什么？（完成某事还是理解某事）
  • 他们处于哪个阶段？（学习中还是工作中）

2. Use the Compass

2. 使用指南罗盘

Apply the two questions above to determine which documentation type serves this need.
通过上述两个问题判断哪种文档类型能满足该需求。

3. Apply the Core Principles

3. 践行核心原则

For Tutorials (learning by doing):
  • You're responsible for the learner's success - every step must work
  • Focus on doing, not explaining
  • Show where they're going upfront
  • Deliver visible results early and often
  • Maintain narrative of expectation ("You'll see...", "Notice that...")
  • Be concrete and specific - one path only, no alternatives
  • Eliminate the unexpected - perfectly repeatable
  • Encourage repetition to build the "feeling of doing"
  • Aspire to perfect reliability
For How-to Guides (working to achieve goals):
  • Address real-world problems, not tool capabilities
  • Assume competence - they know what they want
  • Provide logical sequence that flows with human thinking
  • Address real-world complexity with conditionals ("If X, do Y")
  • Seek flow - anticipate their next move, minimise context switching
  • Omit unnecessary detail - practical usability beats completeness
  • Focus on tasks, not tools
  • Name guides clearly: "How to [accomplish X]"
For Reference (facts while working):
  • Describe, don't instruct - neutral facts only
  • Structure mirrors the product architecture
  • Use standard, consistent patterns throughout
  • Be austere and authoritative - no ambiguity
  • Separate description from instruction
  • Provide succinct usage examples
  • Completeness matters here (unlike how-to guides)
For Explanation (understanding concepts):
  • Talk about the subject from multiple angles
  • Answer "why" - design decisions, history, constraints
  • Make connections to related concepts
  • Provide context and bigger picture
  • Permit opinion and perspective - discuss trade-offs
  • Keep boundaries clear - no instruction or pure reference
  • Take higher, wider perspective
针对教程（在实践中学习）：
  • 你要对学习者的成功负责——每一步都必须可行
  • 聚焦实操，而非讲解
  • 提前告知学习者最终成果
  • 尽早且频繁地展示可见成果
  • 维持预期叙事（“你将会看到……”、“注意……”）
  • 内容要具体明确——仅提供一条路径，不给出替代方案
  • 避免意外情况——确保步骤完全可重复
  • 鼓励重复操作，培养“实操感”
  • 追求完美的可靠性
针对操作指南（为达成目标而工作）：
  • 解决真实世界的问题，而非仅展示工具功能
  • 假设用户具备一定能力——他们清楚自己想要什么
  • 提供符合人类思维逻辑的步骤序列
  • 通过条件语句应对真实场景的复杂性（“如果X，就做Y”）
  • 追求流畅性——预判用户的下一步操作，减少上下文切换
  • 省略不必要的细节——实用性优先于完整性
  • 聚焦任务，而非工具
  • 清晰命名指南：“如何[完成X]”
针对参考文档（工作中的事实参考）：
  • 仅做描述，不做指令——只提供中立事实
  • 结构与产品架构保持一致
  • 全程使用标准、统一的格式
  • 内容严谨权威——无歧义
  • 将描述与指令分离
  • 提供简洁的使用示例
  • 此处完整性至关重要（与操作指南不同）
针对说明性文档（理解概念）：
  • 从多个角度探讨主题
  • 解答“为什么”——设计决策、历史背景、约束条件
  • 建立与相关概念的关联
  • 提供上下文和宏观视角
  • 允许加入观点和视角——讨论权衡取舍
  • 明确边界——不包含指令或纯参考内容
  • 采用更高、更广的视角

4. Use Appropriate Language

4. 使用恰当的语言风格

Tutorials: "We will create..." "First, do X. Now, do Y." "Notice that..." "You have built..."
How-to Guides: "This guide shows you how to..." "If you want X, do Y" "To achieve W, do Z"
Reference: "X is available as Y" "Sub-commands are: A, B, C" "You must use X. Never Y."
Explanation: "The reason for X is..." "W is better than Z, because..." "Some prefer W. This can be effective, but..."
教程：“我们将创建……” “首先，执行X操作。接下来，执行Y操作。” “注意……” “你已经完成了……”
操作指南：“本指南将展示如何……” “如果你想要X，就做Y” “要达成W，执行Z操作”
参考文档：“X可作为Y使用” “子命令包括：A、B、C” “必须使用X，绝对不能使用Y”
说明性文档：“X的原因是……” “W比Z更好，因为……” “有些人偏好W。这可能有效，但……”

5. Check Boundaries

5. 检查边界

Review your content:
  • Does any part serve a different user need?
  • Is there explanation in your tutorial? (Extract and link to it)
  • Are you instructing in reference? (Move to how-to guide)
  • Is there reference detail in your how-to? (Link to reference instead)
If content serves multiple needs, split it and link between documents.
回顾内容：
  • 是否有部分内容服务于不同的用户需求？
  • 教程中是否包含说明性内容？（提取并链接到对应文档）
  • 参考文档中是否包含指令？（移至操作指南）
  • 操作指南中是否包含参考细节？（改为链接到参考文档）
如果内容服务于多种需求，拆分内容并在文档间建立链接。

When Reviewing Existing Documentation

审查现有文档时的流程

Use this iterative workflow:
1. Choose a piece - Any page, section, or paragraph
2. Challenge it with these questions:
  • What user need does this serve?
  • Which documentation type should this be?
  • Does it serve that need well?
  • Is the language appropriate for this type?
  • Does any content belong in a different type?
3. Use the compass if the type is unclear
4. Identify one improvement that would help right now
5. Make that improvement according to Diataxis principles
6. Repeat with another piece
Don't try to restructure everything at once. Structure emerges from improving individual pieces.
遵循以下迭代工作流：
1. 选择审查片段——任意页面、章节或段落
2. 用以下问题审视内容：
  • 该内容满足什么用户需求？
  • 它应该属于哪种文档类型？
  • 它是否很好地满足了该需求？
  • 语言风格是否符合该文档类型？
  • 是否有内容属于其他文档类型？
3. 若类型不明确，使用指南罗盘
4. 确定一项可立即实施的改进措施
5. 依据Diataxis原则实施改进
6. 重复上述步骤处理其他内容
不要试图一次性重构所有内容。结构会从对单个内容片段的改进中自然形成。

Key Principles

核心原则

Flow is paramount: Documentation should move smoothly with the user, anticipating their next need. For how-to guides especially, think: What must they hold in their mind? When can they resolve those thoughts? What will they reach for next?
Boundaries are protective: Keep documentation types separate. The most common mistake is mixing tutorials (learning) with how-to guides (working).
Structure follows content: Don't create empty sections. Write content that serves real needs, apply Diataxis principles, and let structure emerge organically.
One need at a time: Each piece serves one user need. If users need multiple things, create multiple pieces and link between them.
Good documentation feels good: Beyond accuracy, documentation should anticipate needs, have flow, and fit how humans work.
流畅性至上：文档应与用户的操作节奏保持一致，预判他们的下一个需求。尤其对于操作指南，要思考：用户需要记住什么？何时能解决他们的疑问？他们接下来会需要什么？
边界具有保护性：保持不同文档类型的独立性。最常见的错误是混淆教程（学习）和操作指南（工作）。
结构追随内容：不要创建空章节。撰写满足真实需求的内容，践行Diataxis原则，让结构自然形成。
一次满足一个需求：每个内容片段仅服务于一个用户需求。如果用户有多个需求，创建多个内容片段并建立链接。
优质文档应具备易用性：除了准确性，文档还应能预判需求、逻辑流畅，契合人类的工作方式。

Common Mistakes to Avoid

需避免的常见错误

  1. Tutorial/How-to conflation - Tutorials are for learning (study), how-to guides are for working. Signs you've mixed them:
    • Your "tutorial" assumes users know what they want to do
    • Your "tutorial" offers multiple approaches
    • Your "how-to guide" tries to teach basic concepts
    • Your "tutorial" addresses real-world complexity
  2. Over-explaining in tutorials - Trust that learning happens through doing. Give minimal explanation and link to detailed explanation elsewhere.
  3. How-to guides that teach - Assume competence. Don't explain basics.
  4. Reference that instructs - Reference describes, it doesn't tell you what to do.
  5. Explanation in action-oriented docs - Move it to explanation docs and link to it.
  1. 教程与操作指南混淆——教程用于学习（研究阶段），操作指南用于工作（实操阶段）。混淆的迹象：
    • 你的“教程”假设用户清楚自己要做什么
    • 你的“教程”提供多种实现路径
    • 你的“操作指南”试图教授基础概念
    • 你的“教程”涉及真实场景的复杂性
  2. 教程中过度讲解——相信学习源于实践。仅提供必要的讲解，详细说明可链接至其他文档。
  3. 操作指南中包含教学内容——假设用户具备一定能力。不要讲解基础知识。
  4. 参考文档中包含指令——参考文档仅做描述，不告知用户该做什么。
  5. 行动导向文档中包含说明性内容——将其移至说明性文档并建立链接。

Quick Reference Table

快速参考表

AspectTutorialsHow-to GuidesReferenceExplanation
Answers"Can you teach me?""How do I...?""What is...?""Why...?"
User isLearning by doingWorking on taskWorking, needs factsStudying to understand
ContentAction stepsAction stepsInformationInformation
FormA lessonDirectionsDescriptionDiscussion
ResponsibilityOn the teacherOn the userNeutralShared
ToneSupportive, guidingDirect, conditionalAustere, factualDiscursive, contextual
维度教程操作指南参考文档说明性文档
解答的问题“你能教我吗？”“我该如何……？”“这是什么？”“为什么……？”
用户状态在实践中学习处理任务中工作中，需要事实参考为理解而学习中
内容类型操作步骤操作步骤信息内容信息内容
形式课程操作说明描述性内容讨论性内容
责任主体创作者（教师角色）用户中立客观创作者与用户共享
语气支持性、引导性直接、带条件严谨、事实性论述性、情境化

Supporting Files

支持文件

For more detailed guidance, refer to:
  • principles.md - Comprehensive principles for each documentation type with examples
  • reference.md - Quality framework, complex scenarios, and additional guidance
如需更详细的指导，请参考：
  • principles.md - 包含示例的各文档类型综合原则
  • reference.md - 质量框架、复杂场景及额外指导

Output Requirements

输出要求

When applying Diataxis:
  • Be direct and practical
  • Focus on serving user needs
  • Use the compass to resolve uncertainty
  • Cite which documentation type you're applying and why
  • If reviewing docs, be specific about what type it should be and how to improve it
  • Use British English spelling throughout
应用Diataxis框架时：
  • 内容直接实用
  • 聚焦用户需求
  • 用指南罗盘解决不确定性
  • 说明你所应用的文档类型及原因
  • 若审查文档，明确说明它应属于哪种类型及改进方向
  • 全程使用英式英语拼写