title, type, tags, last_updated
| title |
type |
tags |
last_updated |
| Divio Documentation System |
concept |
| documentation |
| knowledge-management |
| methodology |
|
2026-05-01 |
Definition
Divio Documentation System 是由 Divio 提出的文档分类框架，将技术文档分为四个互不重叠的象限，每个象限有明确的目的、受众和写作风格要求。
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
