62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
---
|
||
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 系统组织文档写作方法论
|