---
title: "Divio Documentation System"
type: concept
tags: ["documentation", "knowledge-management", "methodology"]
last_updated: 2026-05-01
---

## Definition
Divio Documentation System 是由 [Divio](https://www.divio.com) 提出的文档分类框架，将技术文档分为四个互不重叠的象限，每个象限有明确的目的、受众和写作风格要求。

## Four Quadrants

### 1. Tutorial（教程）— 学习导向
- **目的**：让读者学会使用某个工具或技术
- **受众**：新手、入门者
- **风格**：循循善诱，像老师带学生一样，解释"为什么这样做"
- **关键特征**：从零开始、有明确起点和终点、成功结果可验证
- **反面教材**：不要写成操作手册（那是 How-to）或参考手册（那是 Reference）

### 2. How-to Guide（操作指南）— 任务导向
- **目的**：帮助读者完成特定任务
- **受众**：已有基础知识的开发者
- **风格**：实用导向，提供解决具体问题的步骤
- **关键特征**：面向结果、不解释基础知识、假设读者知道基本操作
- **反面教材**：不要写成教程（不需要从零开始）或参考文档（不需要穷举选项）

### 3. Reference（参考文档）— 信息导向
- **目的**：准确描述系统功能，提供查找式的信息检索
- **受众**：需要精确信息的开发者
- **风格**：简洁、精确、格式一致、不含解释
- **关键特征**：结构化（按字母/功能分组）、完整枚举所有选项、自动生成
- **反面教材**：不要混入教程内容或解释"为什么"，那会稀释参考价值

### 4. Explanation（解释文档）— 理解导向
- **目的**：帮助读者深入理解某个主题，提供背景和上下文
- **受众**：想理解"为什么"的开发者
- **风格**：探索性、讨论性、允许不同观点
- **关键特征**：不提供步骤、不列举选项、聚焦概念和原理
- **反面教材**：不要写成 How-to（不需要完成任务）或 Reference（不需要列举信息）

## Key Rules

### 绝对禁止：混合象限
- 一个文档页面只属于一个象限
- 混合会导致读者困惑（不知道该看哪部分）和作者维护困难
- 常见错误：把"什么是 X"（Explanation）和"如何用 X"（How-to）写在同一页

### 绝对禁止：在参考文档中写教程内容
- API 参考文档只描述接口，不教如何使用
- Tutorial 是独立页面

### 文档类型与工具的对应关系
| 类型 | 推荐工具 | 生成方式 |
|------|---------|---------|
| Tutorial | Jupyter Notebook, Docusaurus | 人工编写 |
| How-to | Docusaurus, MkDocs | 人工编写 |
| Reference | Sphinx, OpenAPI Generator | 自动生成 + 人工审核 |
| Explanation | Docusaurus, MkDocs | 人工编写 |

## Sources
- [[engineering-technical-writer]] — Technical Writer Agent 使用 Divio 系统组织文档写作方法论