diataxis

使用 Diataxis 方法维护文档

帮助用户遵循 Diataxis 框架组织和维护项目文档。

什么是 Diataxis？

Diataxis（源自古希腊语：dia — “贯穿”，taxis — “安排”）是一种系统化的技术文档方法， 根据用户需求将内容分为四类。请参阅 diataxis.fr 了解完整框架。

类别	侧重点	目的	形式
教程	面向学习	引导初学者逐步学习	一堂课
操作指南	面向任务	帮助完成特定目标	一系列步骤
解释	面向理解	通过讨论加深理解	一篇论述性文章
参考	面向信息	提供精准的技术描述	简洁、准确的事实

指南针 — 用于分类的两个维度

通过两个问题对任何内容进行分类（参见 references/compass.md）：

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

1. “这是关于行动还是认知？” — 读者是要做某件事，还是要理解某件事？
2. “这是关于获取还是应用？” — 读者是在学习，还是在工作？

关键区别

• 教程与操作指南：教程面向学习者进行教学（“跟我来”）；操作指南面向实践者提供指引（“这样做”）。教程从头到尾完整；操作指南从读者可以加入自身工作的合理起点开始，并在合理的节点结束。
• 解释与参考：解释讨论原因（论述性，可以包含观点）；参考陈述内容（简练、权威、没有歧义）。
• 行动与认知：教程和操作指南是实践性的（做事）；解释和参考是理论性的（求知）。
• 获取与应用：教程和解释服务于学习和研习；操作指南和参考服务于工作和编码。

第 1 步：查找现有文档

1. 扫描项目中的文档文件：

   • 查找 docs/、doc/、documentation/ 目录
   • 检查项目根目录中的 Markdown 文件：README.md、CONTRIBUTING.md、CHANGELOG.md
   • 查找其他文档格式：.rst、.adoc、.txt
   • 检查文档配置文件：mkdocs.yml、docusaurus.config.js、conf.py、antora.yml、hugo.toml

2. 阅读现有文档，了解已有内容。

3. 如果没有文档：

   • 告知用户：“未找到文档。让我们从头开始创建文档结构。”
   • 跳转到第 3 步：提出文档结构

第 2 步：为现有文档分类

分析每个文档页面，并将其归入四种 Diataxis 类别之一。

尊重先前的分类决定

在建议重新分类之前，检查 git 历史记录中是否有有意进行的先前调整：

git log --all --oneline --diff-filter=R -- 'docs/**/*.md'

如果某个文件曾被有意地移到不同类别中（例如，提交说明为 docs(diataxis): reclassify X as reference），除非用户 明确要求重新审视，否则请尊重该决定。先前有意进行的重新分类体现了一种判断， 而指南针本身可能无法涵盖这种判断——请向用户指出这一点，而不是擅自推翻决定。

分类规则

使用指南问题和以下信号。各类别的详细写作指南，请参阅 references/ 中的参考文件。

如果页面符合以下特征，则属于教程（参见 references/tutorials.md）：

• 在作者的引导下，带领初学者完成完整的学习体验
• 有明确的起点和目标，并在每个步骤中呈现可见成果
• 使用第一人称复数：“在本教程中，我们将……”“首先，执行 x。现在，执行 y。”
• 遵循循序渐进的叙述，让读者在实践中学习
• 侧重于学习知识，而不是完成现实世界中的任务
• 尽量减少解释，避免离题，改用链接引导读者了解更多信息

如果页面符合以下特征，则属于操作指南（参见 references/how-to-guides.md）：

• 从用户（而非工具）的角度，解决具体、明确的目标
• 假设读者已具备基础知识，并且清楚自己想要什么
• 使用明确的标题：“如何集成监控”，而不是“监控”
• 提供可执行的解决方案：“遇到这种情况时，请按以下步骤操作”
• 从合理的起点开始，并在合理的位置结束，方便读者将其融入自己的工作
• 注重实践，不讲解概念，也不包含参考表格

如果页面符合以下特征，则属于说明（参见 references/explanation.md）：

• 讨论概念、背景、设计决策或权衡
• 回答“能介绍一下……吗？”这类问题——标题前可隐含“关于”
• 关联不同概念并提供背景信息（历史、原因、替代方案）
• 使用说明性散文，可以表达观点并权衡多个角度
• 离开键盘阅读也有意义
• 不吸收操作说明或参考资料的内容

如果页面符合以下特征，则属于参考资料（参见 references/reference.md）：

• 权威地描述 API、配置、CLI 标志或数据结构
• 以便于查阅为目的组织内容（供读者查阅，而非从头到尾阅读）
• 简洁、客观、准确——使用陈述句陈述事实
• 结构与所描述的机制相对应
• 各条目采用一致的标准模式
• 提供展示用法的简要示例，但不进行教学

混合内容

许多页面包含多个类别的内容。请标记这类页面，并建议如何拆分：

• “此页面混合了教程内容（入门部分）和参考资料内容（API 表格）。建议将其拆分为教程页面和参考资料页面。”

边界情况

有些内容类型处于指南分类的边界。不要机械地套用分类标准——应考虑页面的结构和预期用途：

• 故障排除：症状、原因和修复方法的查找表属于参考资料（便于查阅、结构与问题相对应、客观简洁）。逐步引导读者完成诊断流程的页面属于操作指南（以目标为导向的步骤序列）。类别取决于格式，而非主题。
• 常见问题页面：单条问答通常属于参考资料（供读者查阅）。有助于建立理解的精选常见问题集则属于说明。
• 迁移指南：逐步升级说明属于操作指南。讨论变更内容及其原因则属于说明。

遇到边界情况时，不妨考虑：*读者会如何使用这个页面？*查阅信息 → 参考资料。按步骤操作 → 操作指南。

呈现分类结果

将结果呈现为表格：

| 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     |

步骤 3：提出文档结构方案

根据分析结果，提出符合 Diataxis 的目录结构。

标准目录布局

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.md

适配规则

• 适配现有工具：如果项目使用 mkdocs、docusaurus、antora、hugo 或类似工具，请提出符合该工具惯例的结构。
• 适配现有结构：如果项目已有部分符合 Diataxis 的文档结构，请提出最小改动方案，使其完全符合 Diataxis，而不是彻底重构。
• 保留有效内容：不要建议移动已分类妥当的内容。
• 遵循项目惯例：如果项目使用特定命名惯例（kebab-case、snake_case 等），请遵循该惯例。

找出文档缺口

对现有内容分类后，找出缺失的部分：

• 没有教程？ 建议创建入门教程。
• 没有操作指南？ 建议为最常见的任务（安装、配置、部署）编写指南。
• 没有解释文档？ 建议编写架构或设计决策文档。
• 没有参考文档？ 建议编写 API、配置或 CLI 参考页面。

清晰地列出缺口：

Documentation gaps identified:
- [ ] Missing: Tutorial for getting started
- [ ] Missing: How-to guide for deployment
- [ ] Missing: Reference for configuration options
- [x] Covered: Architecture explanation exists

第 4 步：执行变更

始终先询问用户，再进行变更。 提出计划并等待批准。

重组文档时

1. 列出拟议的文件移动和重命名
2. 等待用户批准
3. 将文件移动到新位置
4. 更新文档页面之间的内部链接
5. 更新导航配置（mkdocs.yml、侧边栏配置等）（如适用）
6. 确认没有遗留失效链接

创建新页面时

1. 列出建议创建的页面
2. 等待用户批准
3. 使用 references/templates.md 中对应的模板（教程、操作指南、解释文档或参考文档），按相应类别规范创建页面
4. 根据项目分析（源代码、现有文档、配置文件）填写内容

改进现有页面时

如果页面分类正确，但需要改进以更好地遵循 Diataxis 原则：

1. 指出具体问题（内容混杂、语气不当、结构缺失）
2. 向用户提出建议的更改
3. 获得批准后应用更改

重要指南

• 不要强行套用框架：如果项目规模较小，且单个 README 已能全面说明情况，请如实说明。Diataxis 对文档需求较多的项目最有价值。
• 务实处理：部分整理过的文档集胜过完全没有文档。建议循序渐进地改进，而不是要求尽善尽美。
• 保留内容：重组时绝不要删除内容。可以移动和重新组织，但要保留所有现有信息。
• 维护链接：移动文件时，更新所有交叉引用和导航配置。
• 尊重用户的决定：如果用户不同意分类或重组建议，请接受用户的决定并作相应调整。
• 关注质量：Diataxis 有助于提升质量，但无法保证质量——准确性、完整性和良好的文笔仍由作者负责。有关质量维度，请参阅 references/quality.md。
• 有疑问时使用指南针：如果分类不明确或写作遇到困难，请运用指南针中的两个问题。请参阅 references/compass.md。

参考文档

各类别的详细写作指南，摘自 diataxis.fr：

• references/tutorials.md — 教学原则、语言规范、反模式
• references/how-to-guides.md — 写作原则、范围、与教程的区别
• references/explanation.md — 特征、讨论领域、命名测试
• references/reference.md — 精简原则、结构映射、示例
• references/compass.md — 用于分类的双轴决策工具
• references/quality.md — 功能质量和深层质量维度