diataxis
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMaintain Documentation with the Diataxis Method
基于Diataxis方法维护文档
You are helping the user organize and maintain their project documentation following the Diataxis framework.
你将帮助用户遵循Diataxis框架来组织和维护项目文档。
What is Diataxis?
什么是Diataxis？
Diataxis (from Ancient Greek: dia — "across", taxis — "arrangement") is a systematic
approach to technical documentation that organizes content into four categories based on
user needs. See diataxis.fr for the full framework.
| Category | Orientation | Purpose | Form |
|---|---|---|---|
| Tutorials | Learning-oriented | Guide a beginner through learning | A lesson |
| How-to guides | Task-oriented | Help accomplish a specific goal | A series of steps |
| Explanation | Understanding-oriented | Deepen understanding through discussion | A discursive essay |
| Reference | Information-oriented | Provide precise technical descriptions | Dry, accurate facts |
Diataxis（源自古希腊语：dia —— "贯穿"，taxis —— "排列"）是一种系统化的技术文档方法，它根据用户需求将内容分为四个类别。完整框架请查看 diataxis.fr。
| 类别 | 定位 | 用途 | 形式 |
|---|---|---|---|
| 教程（Tutorials） | 以学习为导向 | 引导初学者完成学习过程 | 课程形式 |
| 操作指南（How-to guides） | 以任务为导向 | 帮助完成特定目标 | 步骤序列 |
| 解释说明（Explanation） | 以理解为导向 | 通过讨论深化理解 | 论述性文章 |
| 参考文档（Reference） | 以信息为导向 | 提供精准的技术描述 | 简洁准确的事实内容 |
The Compass — Two Axes for Classification
分类指南针——两大分类轴
Use two questions to classify any content (see references/compass.md):
| Acquisition (study) | Application (work) | |
|---|---|---|
| Action (practical) | Tutorial | How-to guide |
| Cognition (theoretical) | Explanation | Reference |
- "Is this about action or cognition?" — Does the reader do something or understand something?
- "Is this about acquisition or application?" — Is the reader studying or working?
通过两个问题对任何内容进行分类（查看 references/compass.md）：
| 习得（学习） | 应用（工作） | |
|---|---|---|
| 行动（实践） | 教程 | 操作指南 |
| 认知（理论） | 解释说明 | 参考文档 |
- "这是关于行动还是认知？" —— 读者是要动手操作还是理解概念？
- "这是关于习得还是应用？" —— 读者是在学习还是在工作？
Key Distinctions
核心区别
- Tutorials vs How-to guides: Tutorials teach ("follow me") for learners; how-to guides direct ("do this") for practitioners. Tutorials are complete end-to-end; how-to guides start and end at reasonable points the reader joins to their own work.
- Explanation vs Reference: Explanation discusses why (discursive, admits opinion); reference states what (austere, authoritative, no ambiguity).
- Action vs Cognition: Tutorials and how-to guides are practical (doing). Explanation and reference are theoretical (knowing).
- Acquisition vs Application: Tutorials and explanation serve learning/studying. How-to guides and reference serve working/coding.
- 教程 vs 操作指南：教程面向学习者，以"跟着我做"的方式教学；操作指南面向从业者，以"做这个"的方式指导。教程是完整的端到端流程；操作指南的起止点符合合理场景，读者可将其融入自身工作流程。
- 解释说明 vs 参考文档：解释说明探讨"为什么"（论述性，允许包含观点）；参考文档陈述"是什么"（严谨、权威、无歧义）。
- 行动 vs 认知：教程和操作指南偏实践（动手）。解释说明和参考文档偏理论（认知）。
- 习得 vs 应用：教程和解释说明服务于学习/研究。操作指南和参考文档服务于工作/编码。
Step 1: Discover Existing Documentation
步骤1：梳理现有文档
-
Scan the project for documentation files:
- Look for ,
docs/,doc/directoriesdocumentation/ - Check for markdown files at the project root: ,
README.md,CONTRIBUTING.mdCHANGELOG.md - Look for other documentation formats: ,
.rst,.adoc.txt - Check for documentation configuration: ,
mkdocs.yml,docusaurus.config.js,conf.py,antora.ymlhugo.toml
- Look for
-
Read existing documentation to understand what is already covered.
-
If no documentation exists:
- Inform the user: "No documentation found. Let's create a documentation structure from scratch."
- Skip to Step 3: Propose Documentation Structure
-
扫描项目中的文档文件：
- 查找 、
docs/、doc/目录documentation/ - 检查项目根目录下的Markdown文件：、
README.md、CONTRIBUTING.mdCHANGELOG.md - 查找其他文档格式：、
.rst、.adoc.txt - 检查文档配置文件：、
mkdocs.yml、docusaurus.config.js、conf.py、antora.ymlhugo.toml
- 查找
-
阅读现有文档，了解已覆盖的内容。
-
若不存在任何文档：
- 告知用户："未找到任何文档。让我们从零开始创建文档结构。"
- 跳至 步骤3：提议文档结构
Step 2: Classify Existing Documentation
步骤2：分类现有文档
Analyze each documentation page and classify it into one of the four Diataxis categories.
分析每个文档页面，并将其归类为Diataxis的四个类别之一。
Respect Prior Classification Decisions
尊重已有的分类决策
Before suggesting reclassification, check git history for deliberate prior moves:
bash
git log --all --oneline --diff-filter=R -- 'docs/**/*.md'If a file was intentionally moved between categories (e.g., a commit message like
), respect that decision unless the user
explicitly asks to revisit it. A prior deliberate reclassification reflects a judgment
that the compass alone may not capture — flag it to the user rather than overriding it.
docs(diataxis): reclassify X as reference在建议重新分类前，查看Git历史记录中是否有刻意的移动操作：
bash
git log --all --oneline --diff-filter=R -- 'docs/**/*.md'如果文件曾被有意在类别间移动（例如提交信息为 ），请尊重该决策，除非用户明确要求重新审视。之前的刻意重分类反映了指南针可能未涵盖的判断——应向用户标记该情况而非直接覆盖。
docs(diataxis): reclassify X as referenceClassification Rules
分类规则
Use the compass questions and these signals. For detailed writing guidance per category,
see the reference files in .
references/A page is a Tutorial if it (see references/tutorials.md):
- Guides a beginner through a complete learning experience under the author's direction
- Has a clear starting point and end goal, delivering visible results at each step
- Uses first-person plural: "In this tutorial, we will...", "First, do x. Now, do y."
- Follows a sequential narrative where the reader learns by doing
- Focuses on learning acquisition, not on accomplishing a real-world task
- Minimises explanation — links out instead of digressing
A page is a How-to guide if it (see references/how-to-guides.md):
- Addresses a specific, concrete goal from the user's perspective (not the tool's)
- Assumes the reader already has basic knowledge and knows what they want
- Uses precise titles: "How to integrate monitoring", not "Monitoring"
- Provides an executable solution: "if facing this situation, follow these steps"
- Starts and ends at reasonable points — reader joins it to their own work
- Stays practical without teaching concepts or including reference tables
A page is Explanation if it (see references/explanation.md):
- Discusses concepts, background, design decisions, or trade-offs
- Answers "Can you tell me about...?" — titles work with an implicit "About" prefix
- Makes connections between concepts and provides context (history, reasons, alternatives)
- Uses discursive prose that admits opinion and weighs multiple perspectives
- Could make sense to read away from the keyboard
- Resists absorbing instruction or reference material
A page is Reference if it (see references/reference.md):
- Describes APIs, configurations, CLI flags, or data structures authoritatively
- Is structured for lookup (consulted, not read end-to-end)
- Is austere, factual, and precise — states facts using declarative language
- Mirrors the structure of the machinery it describes
- Uses consistent, standard patterns across all entries
- Provides minimal examples that demonstrate usage without teaching
使用指南针问题和以下信号。各分类的详细写作指南请查看 下的参考文件。
references/某页面属于教程（Tutorial）如果它（查看 references/tutorials.md）：
- 在作者的引导下，指导初学者完成完整的学习体验
- 有明确的起点和终点目标，每一步都能呈现可见成果
- 使用第一人称复数："在本教程中，我们将..."、"首先，执行x操作。现在，执行y操作。"
- 遵循连贯的叙事结构，读者通过动手操作学习
- 聚焦于知识习得，而非完成实际任务
- 尽量减少解释——通过链接跳转而非展开论述
某页面属于操作指南（How-to guide）如果它（查看 references/how-to-guides.md）：
- 从用户视角出发，解决具体、明确的目标（而非工具视角）
- 假设读者已具备基础知识，清楚自己的需求
- 使用精准标题："如何集成监控"，而非"监控"
- 提供可执行的解决方案："若遇到此情况，请遵循以下步骤"
- 起止点符合合理场景——读者可将其融入自身工作流程
- 保持实用性，不教授概念或包含参考表格
某页面属于解释说明（Explanation）如果它（查看 references/explanation.md）：
- 探讨概念、背景、设计决策或权衡方案
- 回答"你能告诉我关于...？"——标题可隐式添加"关于"前缀
- 建立概念间的关联并提供上下文（历史、原因、替代方案）
- 使用论述性文字，允许包含观点并权衡多种视角
- 脱离键盘阅读也能理解
- 避免包含操作指令或参考内容
某页面属于参考文档（Reference）如果它（查看 references/reference.md）：
- 权威描述API、配置、CLI标志或数据结构
- 为查阅而设计（用于检索，而非从头读到尾）
- 简洁、真实、精准——使用陈述性语言呈现事实
- 镜像所描述机制的结构
- 所有条目使用一致的标准格式
- 提供展示用法的极简示例，而非教学
Mixed Content
混合内容
Many pages contain content from multiple categories. Flag these for the user and suggest how to split them:
- "This page mixes tutorial content (the getting started section) with reference content (the API table). Consider splitting into a tutorial and a reference page."
许多页面包含多个类别的内容。向用户标记此类页面并建议拆分方式：
- "此页面混合了教程内容（入门章节）和参考内容（API表格）。建议拆分为教程页面和参考页面。"
Boundary Cases
边界情况
Some content types sit at the compass boundary. Do not apply the compass mechanically —
consider the page's structure and intended use:
- Troubleshooting: A lookup table of symptoms, causes, and fixes is Reference (structured for consultation, mirrors problem structure, austere facts). A page that walks through a diagnostic process step-by-step is How-to (goal-oriented sequence). The format determines the category, not the subject matter.
- FAQ pages: Individual Q&A entries are often Reference (lookup). A curated FAQ that builds understanding is Explanation.
- Migration guides: Step-by-step upgrade instructions are How-to. A discussion of what changed and why is Explanation.
When in doubt about a boundary case, consider: how will the reader use this page?
Consulted for lookup → Reference. Followed as steps → How-to.
部分内容类型处于指南针的边界。不要机械套用指南针——需考虑页面的结构和预期用途：
- 故障排查：症状、原因和修复方案的查找表属于参考文档（为查阅设计，镜像问题结构，内容简洁准确）。逐步引导诊断流程的页面属于操作指南（目标导向的步骤序列）。类别由格式决定，而非主题。
- FAQ页面：单个问答条目通常属于参考文档（用于检索）。旨在构建理解的精选FAQ属于解释说明。
- 迁移指南：分步升级说明属于操作指南。讨论变更内容及原因的部分属于解释说明。
若对边界情况存疑，请思考：读者将如何使用此页面？ 用于查阅→参考文档。按步骤执行→操作指南。
Present Classification Results
呈现分类结果
Present results as a table:
text
| File | Current Category | Suggested Category | Notes |
|--------------------------|------------------|--------------------|--------------------------------|
| docs/getting-started.md | - | Tutorial | Good tutorial structure |
| docs/api.md | - | Reference | Contains some how-to content |
| docs/architecture.md | - | Explanation | Well-structured explanation |以表格形式呈现结果：
text
| 文件路径 | 当前类别 | 建议类别 | 备注 |
|--------------------------|----------|----------|-----------------------|
| docs/getting-started.md | - | 教程 | 教程结构合理 |
| docs/api.md | - | 参考文档 | 包含部分操作指南内容 |
| docs/architecture.md | - | 解释说明 | 结构清晰的解释内容 |Step 3: Propose Documentation Structure
步骤3：提议文档结构
Based on the analysis, propose a Diataxis-aligned directory structure.
基于分析结果，提议符合Diataxis规范的目录结构。
Standard Directory Layout
标准目录布局
text
docs/
tutorials/ # Learning-oriented
getting-started.md
first-project.md
how-to/ # Task-oriented
install.md
configure.md
deploy.md
explanation/ # Understanding-oriented
architecture.md
design-decisions.md
reference/ # Information-oriented
api.md
configuration.md
cli.mdtext
docs/
tutorials/ # 以学习为导向
getting-started.md
first-project.md
how-to/ # 以任务为导向
install.md
configure.md
deploy.md
explanation/ # 以理解为导向
architecture.md
design-decisions.md
reference/ # 以信息为导向
api.md
configuration.md
cli.mdAdaptation Rules
适配规则
- Adapt to existing tooling: If the project uses mkdocs, docusaurus, antora, hugo, or similar, propose a structure compatible with that tool's conventions.
- Adapt to existing structure: If the project already has a docs structure that partially aligns with Diataxis, propose minimal changes to align it fully rather than a complete restructure.
- Keep what works: Do not propose moving content that is already well-categorized.
- Respect the project conventions: If the project uses a specific naming convention (kebab-case, snake_case, etc.), follow it.
- 适配现有工具：如果项目使用mkdocs、docusaurus、antora、hugo或类似工具，提议符合该工具约定的结构。
- 适配现有结构：如果项目已有部分符合Diataxis的文档结构，提议最小化变更以完全对齐，而非彻底重构。
- 保留有效内容：不要提议移动已合理分类的内容。
- 遵循项目约定：如果项目使用特定命名规范（短横线命名、下划线命名等），请遵循该规范。
Identify Documentation Gaps
识别文档缺口
After classifying existing content, identify missing pieces:
- No tutorials? Suggest creating a getting-started tutorial.
- No how-to guides? Suggest guides for the most common tasks (installation, configuration, deployment).
- No explanation? Suggest architecture or design decision documents.
- No reference? Suggest API, configuration, or CLI reference pages.
Present gaps clearly:
text
Documentation gaps identified:
- [ ] Missing: Tutorial for getting started
- [ ] Missing: How-to guide for deployment
- [ ] Missing: Reference for configuration options
- [x] Covered: Architecture explanation exists分类现有内容后，识别缺失部分：
- 无教程？ 建议创建入门教程。
- 无操作指南？ 建议为最常见任务（安装、配置、部署）创建指南。
- 无解释说明？ 建议创建架构或设计决策文档。
- 无参考文档？ 建议创建API、配置或CLI参考页面。
清晰呈现缺口：
text
已识别的文档缺口：
- [ ] 缺失：入门教程
- [ ] 缺失：部署操作指南
- [ ] 缺失：配置选项参考文档
- [x] 已覆盖：架构解释说明已存在Step 4: Execute Changes
步骤4：执行变更
Always ask the user before making changes. Present the plan and wait for approval.
执行变更前务必征得用户同意。呈现计划并等待批准。
When Restructuring
重构时
- Present the proposed file moves and renames
- Wait for user approval
- Move files to their new locations
- Update any internal links between documentation pages
- Update navigation configuration (mkdocs.yml, sidebar config, etc.) if applicable
- Verify no broken links remain
- 呈现提议的文件移动和重命名方案
- 等待用户批准
- 将文件移动至新位置
- 更新文档页面间的内部链接
- 若适用，更新导航配置（mkdocs.yml、侧边栏配置等）
- 验证无失效链接
When Creating New Pages
创建新页面时
- Present which pages you suggest creating
- Wait for user approval
- Create pages with proper structure for their category:
Tutorial template (see references/tutorials.md for writing principles):
markdown
undefined- 呈现建议创建的页面
- 等待用户批准
- 为对应类别创建结构规范的页面：
教程模板（写作原则请查看 references/tutorials.md）：
markdown
undefined[Title — state what we will build/create]
[标题——说明我们将构建/创建的内容]
In this tutorial, we will [concrete goal — what the reader will have at the end].
在本教程中，我们将[具体目标——读者最终将完成的成果]。
Before you begin
准备工作
- [Prerequisite 1]
- [前置条件1]
Step 1: [First step — concrete action]
步骤1：[第一步——具体操作]
[Direct instruction. Show expected output after each step.]
The output should look something like:
[example output][直接指令。展示每一步后的预期输出。]
输出示例如下：
[示例输出]Step 2: [Second step — builds on previous]
步骤2：[第二步——基于上一步展开]
[Direct instruction. Point out what to notice.]
Notice that [observation that closes a learning loop].
[直接指令。指出需要注意的点。]
请注意[完成学习闭环的观察结论]。
What you've built
你已完成的内容
You have [concrete summary of achievement].
你已[具体成果总结]。
Next steps
下一步
- [Link to next tutorial or related how-to guide]
**How-to guide template** (see [references/how-to-guides.md](references/how-to-guides.md) for writing principles):
```markdown- [链接至下一个教程或相关操作指南]
**操作指南模板**（写作原则请查看 [references/how-to-guides.md](references/how-to-guides.md)）：
```markdownHow to [accomplish specific goal]
如何[完成特定目标]
This guide shows you how to [task description].
本指南将展示如何[任务描述]。
Prerequisites
前置条件
- [Prerequisite — assume basic competence]
- [前置条件——假设用户具备基础能力]
Steps
步骤
1. [First step]
1. [第一步]
[Concise, actionable instruction]
[简洁、可执行的指令]
2. [Second step]
2. [第二步]
[Concise, actionable instruction]
Refer to the x reference for a full list of options.
[简洁、可执行的指令]
如需完整选项列表，请参考x参考文档。
Troubleshooting
故障排查
[Common problem]
[常见问题]
If you want [x], do [y].
**Explanation template** (see [references/explanation.md](references/explanation.md) for writing principles):
```markdown若你需要[x]，请执行[y]。
**解释说明模板**（写作原则请查看 [references/explanation.md](references/explanation.md)）：
```markdown[Topic — should read naturally after "About"]
[主题——添加"关于"前缀后读起来自然]
[Opening paragraph that establishes context and scope]
[开篇段落，建立上下文和范围]
Background
背景
[Historical context, design decisions, or foundational concepts]
[历史背景、设计决策或基础概念]
[Main concept]
[核心概念]
[Discursive explanation — make connections, provide context, admit perspective]
The reason for [x] is because [historical/technical context].
[W] is better than [z] because [reasoning].
[论述性解释——建立关联、提供上下文、阐述视角]
[x]的原因是[历史/技术背景]。
[W]优于[z]的原因是[推理过程]。
Alternatives and trade-offs
替代方案与权衡
[Discussion of other approaches and why this one was chosen]
[讨论其他方案及选择当前方案的原因]
Further reading
延伸阅读
- [Related resources]
**Reference template** (see [references/reference.md](references/reference.md) for writing principles):
```markdown- [相关资源]
**参考文档模板**（写作原则请查看 [references/reference.md](references/reference.md)）：
```markdown[Component] Reference
[组件]参考文档
[One-line description of what this reference covers]
[一句话描述本参考文档涵盖的内容]
[Section — mirrors structure of the machinery]
[章节——镜像所描述机制的结构]
| Parameter | Type | Default | Description |
|---|---|---|---|
| string | - | Description |
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| string | - | 描述 |
[API/Function/Command]
[API/函数/命令]
Signature:
function_name(param1, param2)Parameters:
- (type) — Description
param1 - (type) — Description
param2
Returns: Description of return value
Example:
result = function_name("value", 42)
1. Fill in content based on project analysis (source code, existing docs, configuration files)签名：
function_name(param1, param2)参数：
- (类型) —— 描述
param1 - (类型) —— 描述
param2
返回值： 返回值描述
示例：
result = function_name("value", 42)
1. 基于项目分析（源代码、现有文档、配置文件）填充内容When Improving Existing Pages
优化现有页面时
If a page is already in the right category but needs improvement to better follow Diataxis principles:
- Identify specific issues (mixed content, wrong tone, missing structure)
- Present suggested changes to the user
- Apply changes after approval
若页面已属于正确类别，但需优化以更好遵循Diataxis原则：
- 识别具体问题（混合内容、语气不当、结构缺失）
- 向用户呈现建议的变更内容
- 获得批准后应用变更
Important Guidelines
重要准则
- Do not force the framework: If the project is small and a single README covers everything well, say so. Diataxis is most valuable for projects with substantial documentation needs.
- Be pragmatic: A partially-organized documentation set is better than no documentation. Suggest incremental improvements rather than demanding perfection.
- Preserve content: When restructuring, never delete content. Move and reorganize, but keep all existing information.
- Maintain links: When moving files, update all cross-references and navigation configurations.
- Respect the user's decisions: If the user disagrees with a classification or restructuring suggestion, accept their decision and adjust accordingly.
- Quality awareness: Diataxis facilitates quality but cannot guarantee it — accuracy, completeness, and good writing remain the author's responsibility. See references/quality.md for quality dimensions.
- Use the compass when in doubt: When classification is unclear or writing feels difficult, apply the two compass questions. See references/compass.md.
- 不要强行套用框架：如果项目规模较小，单个README即可覆盖所有内容，请如实告知。Diataxis最适用于有大量文档需求的项目。
- 务实为主：部分组织的文档集优于无文档。建议渐进式改进，而非追求完美。
- 保留内容：重构时切勿删除内容。可移动和重组，但需保留所有现有信息。
- 维护链接：移动文件时，更新所有交叉引用和导航配置。
- 尊重用户决策：若用户不同意分类或重构建议，请接受其决策并相应调整。
- 质量意识：Diataxis有助于提升质量，但无法保证质量——准确性、完整性和良好的写作仍需作者负责。查看 references/quality.md 了解质量维度。
- 存疑时使用指南针：若分类不明确或写作遇到困难，请应用指南针的两个问题。查看 references/compass.md。
Reference Documents
参考文档
Detailed writing guidance for each category, extracted from diataxis.fr:
- references/tutorials.md — Pedagogical principles, language conventions, anti-patterns
- references/how-to-guides.md — Writing principles, scope, distinction from tutorials
- references/explanation.md — Characteristics, discussion areas, naming test
- references/reference.md — Austerity principles, structure mirroring, examples
- references/compass.md — Two-axis decision tool for classification
- references/quality.md — Functional and deep quality dimensions
各分类的详细写作指南，摘自 diataxis.fr：
- references/tutorials.md —— 教学原则、语言规范、反模式
- references/how-to-guides.md —— 写作原则、范围、与教程的区别
- references/explanation.md —— 特征、讨论领域、命名测试
- references/reference.md —— 简洁性原则、结构镜像、示例
- references/compass.md —— 双轴分类决策工具
- references/quality.md —— 功能与深度质量维度