文档写作理论 - Diátaxis

一、核心概念：四大文档类型

Diátaxis 框架将技术文档划分为四个象限，基于两个维度：

• 学习（Learning）vs 工作（Working）：用户是在学习知识还是解决实际问题
• 理论（Theory）vs 实践（Practice）：内容偏向概念理解还是动手操作

二、四大类型详解与写作规范

2.1 Tutorials（教程）- 入门体验

目的：让初学者通过实际操作获得成就感，建立信心。

特点：

• 面向零基础的初学者
• 必须是可复现的完整流程
• 强调学习体验而非生产环境的最佳实践
• 结果可预测，避免让用户陷入死胡同

结构模板：

# 教程标题 ## 你将学到什么 - 完成 [具体成果] - 掌握 [关键概念] ## 前置要求 - 已安装 [软件/环境] - 具备 [基础知识] ## 步骤 1. [具体动作] - [预期结果] 2. [具体动作] - [预期结果] ... ## 验证 [如何确认成功完成] ## 下一步 [推荐阅读/练习]

写作原则：

• ✅ 使用命令式：“点击按钮”、“输入命令”
• ✅ 每个步骤立即产生可见反馈
• ❌ 不解释原理（留在 Explanation 中）
• ❌ 不提供替代方案（保持路径唯一）

2.2 How-to Guides（操作指南）- 问题解决

目的：帮助用户完成特定任务，解决实际问题。

特点：

• 面向已具备基础知识的用户
• 聚焦单一目标，步骤导向
• 假设用户知道为什么要做，只告诉怎么做
• 可接受多种实现方式

结构模板：

# 如何 [完成任务] ## 目标 [一句话描述要达成的结果] ## 前置条件 - [环境/权限要求] - [依赖项] ## 步骤 1. [动作] 2. [动作] ... ## 故障排除 | 问题 | 原因 | 解决方案 | |------|------|----------| | ... | ... | ... | ## 相关操作 - [链接到其他 How-to]

与 Tutorials 的区别：

2.3 Reference（参考）- 准确信息

目的：提供精确、完整的技术描述。

特点：

• 描述性而非指导性
• 结构一致、可预测
• 覆盖所有选项/参数
• 与代码/实现严格同步

适用内容：

• API 文档
• 配置文件说明
• CLI 命令参数
• 错误代码列表

结构模板（以 API 为例）：

# API 参考 ## [Endpoint Name] `METHOD /path/to/endpoint` ### 描述 [一句话功能描述] ### 请求参数 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | ... | ... | ... | ... | ### 响应 #### 成功 (200) ```json { "field": "type" }

错误码

示例

[完整请求/响应示例]

**写作原则**： - ✅ 机器可读的结构（便于自动生成） - ✅ 版本信息明确标注 - ❌ 不包含使用场景说明（放在 How-to 中） - ❌ 不解释设计原理（放在 Explanation 中） --- #### 2.4 Explanation（解释）- 深度理解 **目的**：帮助用户理解概念、原理和背景知识。 **特点**： - **理论性**、论述性 - 回答 **"为什么"** 和 **"如何运作"** - 建立**概念之间的联系** - 不教授具体操作 **适用主题**： - 架构设计决策 - 算法原理 - 最佳实践背后的原因 - 历史背景和演进 **结构模板**： ```markdown # [概念名称] ## 概述 [是什么 + 为什么重要] ## 核心原理 [详细解释工作机制] ## 设计考量 [为什么选择这种方式] ## 与其他方案的比较 | 方案 | 优点 | 缺点 | 适用场景 | |------|------|------|----------| | A | ... | ... | ... | | B | ... | ... | ... | ## 实际影响 [对开发/使用的影响] ## 延伸阅读 [相关 Explanation 文章]

写作原则：

• ✅ 多角度阐述（历史、技术、业务）
• ✅ 使用类比和图示
• ✅ 承认复杂性和权衡
• ❌ 不包含操作步骤
• ❌ 不罗列参数细节

三、落地实施：文档架构设计

3.1 网站/文档结构建议

docs/ ├── tutorials/ # 入门教程 │ ├── getting-started/ │ ├── build-your-first-app/ │ └── ... ├── how-to/ # 操作指南 │ ├── deploy/ │ ├── configure/ │ ├── troubleshoot/ │ └── ... ├── reference/ # 参考文档 │ ├── api/ │ ├── cli/ │ ├── configuration/ │ └── ... └── explanation/ # 概念解释 ├── architecture/ ├── design-patterns/ └── ...

3.2 导航设计原则

3.3 交叉引用策略

在每种类型文档中，明确引导用户到其他类型：

<!-- 在 Tutorial 结尾 --> > 📚 **想深入了解原理？** 阅读 [架构设计说明](/explanation/architecture) > 🛠️ **准备投入生产？** 查看 [部署指南](/how-to/deploy) <!-- 在 How-to 开头 --> > 💡 **不熟悉此功能？** 先完成 [入门教程](/tutorials/getting-started) > 📖 **需要参数详情？** 查看 [API 参考](/reference/api) <!-- 在 Reference 中 --> > 🎓 **不知道如何使用？** 参考 [操作指南](/how-to/) > 🤔 **想了解设计原因？** 阅读 [技术决策](/explanation/design-decisions)

四、内容生产工作流

4.1 内容规划矩阵

在规划文档时，先确定内容类型：

4.2 写作检查清单

Tutorial 检查清单：

• 从完全零基础开始
• 每个步骤有明确的预期结果
• 用户能在 15-30 分钟内完成
• 不包含"可选步骤"
• 结尾有成功验证方法

How-to 检查清单：

• 标题以"如何"开头
• 前置条件明确
• 步骤可跳过已掌握的部分
• 包含故障排除
• 提供替代方案（如适用）

Reference 检查清单：

• 结构一致（与其他参考文档）
• 信息完整（无遗漏参数/选项）
• 与代码版本同步
• 机器可解析（便于自动生成）

Explanation 检查清单：

• 回答"为什么"而不仅是"是什么"
• 使用具体例子说明抽象概念
• 承认复杂性和权衡
• 不混入操作指令

五、工具与实践

5.1 推荐工具链

5.2 MkDocs 配置示例（Material 主题）

# mkdocs.ymlsite_name:我的文档theme:name:materialfeatures:-navigation.tabs-navigation.sections-navigation.expand-search.highlightnav:-首页:index.md-Tutorials:-tutorials/getting-started.md-tutorials/advanced-features.md-How-to Guides:-how-to/deploy.md-how-to/configure.md-Reference:-reference/api.md-reference/cli.md-Explanation:-explanation/architecture.md-explanation/design-patterns.mdplugins:-search-minify

5.3 团队协作规范

1. 文档评审：PR 模板中要求标注文档类型

   ## 文档类型 - [ ] Tutorial - [ ] How-to Guide - [ ] Reference - [ ] Explanation ## 检查清单 [对应类型的检查项]

2. 版本管理：Reference 必须与代码版本严格对应，其他类型可相对独立更新

3. 内容重用：使用 Markdown 的 include 功能提取公共片段

   --8<-- "common/prerequisites.md"

六、常见错误与纠正