documentation

适用场景

当你需要按照 Diátaxis 框架创建、审查或改进技术文档时，可使用此技能。例如：

• 创建用户指南
• 编写 API 文档
• 编写教程内容
• 重构现有文档，以便更好地满足不同用户的需求和适用场景

说明

将文档分为四种不同类型——教程、操作指南、参考资料和说明文——分别满足不同用户的需求和适用场景。

在创建文档之前，务必询问用户的使用场景、受众和目标等澄清问题。

---

第 1 步 — 确定文档类型

根据用户表达的信号，使用以下判断清单：

用户信号	文档类型
“我是 X 的新手，想学习”／“带我一步步完成”	教程
“如何……？”／“我需要完成 X”	操作指南
“X 的参数／选项／语法是什么？”	参考资料
“X 为什么这样运行？”／“帮我理解 X”	说明文

快速判断流程：

• 用户是否要通过动手实践来首次学习？→ 教程
• 用户是否需要解决一个自己已经理解的特定问题？→ 操作指南
• 用户是否需要查阅技术事实？→ 参考资料
• 用户是否想了解概念背景？→ 说明文

---

第 2 步 — 应用特定类型的模式

教程（以学习为导向）

• **标题模式：**以动词开头 — “构建你的第一个 X”、“从头创建 Y”
• 结构：目标 → 先决条件 → 编号步骤 → 每一步都能立即验证的结果 → 最终成果
• 尽量减少解释，尽可能让用户动手实践
• 每一步都必须产生可见、可测试的结果
• **验证标准：**初学者无需外部帮助即可完成教程

引言示例：

“在本教程中，你将使用 Express 构建一个简单的 REST API。完成后，你将拥有一个能够响应 GET 请求的运行中服务。无需具备 Express 经验。”

---

操作指南（以解决问题为导向）

• **标题模式：**围绕一项任务来写 — “如何配置 X”、“如何将 Y 部署到 Z”
• 结构：目标说明 → 假设条件／先决条件 → 编号步骤 → 预期结果
• 假定读者具备基础知识；省略概念性解释
• 允许不同做法；如有替代方案，请注明
• **验证标准：**有经验的用户无需困惑或返工即可完成任务

引言示例：

“本指南介绍如何为现有 Express 应用添加 JWT 身份验证。默认你已有一个可运行的 Express 服务，并且基本了解中间件。”

---

参考资料（以信息为导向）

• **标题模式：**直接命名对象 — “配置选项”、“API 端点”、“CLI 标志”
• 结构：每个条目都使用一致、可重复的格式（名称 → 类型 → 默认值 → 描述 → 示例）
• 陈述事实；除最基本的用法示例外，避免提供操作说明
• 保持内容最新；必要时注明版本
• **验证标准：**用户无需阅读周边内容，就能在 30 秒内查到特定事实

条目示例：

timeout （整数，默认值：5000） 等待响应的最长时间（毫秒），超时后请求将失败。 示例： { timeout: 3000 }

---

说明文（以帮助理解为导向）

• **标题模式：**围绕概念来写 — “X 的工作原理”、“理解 Y”、“Z 为什么这样设计”
• 结构：背景 → 核心概念 → 替代方案／权衡 → 更高层次的视角
• 避免分步操作说明或技术规范
• **验证标准：**阅读后，用户能用自己的话解释这一概念，并理解相关设计决策背后的原因

引言示例：

“身份验证和授权经常被混淆。本页面将解释二者的区别、二者为何都很重要，以及常见模式（会话、令牌、OAuth）如何以不同方式处理各自的问题。”

步骤 3 — 保持区分并促进整合

• 确保每篇文档只属于一种类型——不要将教程步骤与参考表格或概念性说明混在一起
• 在不同类型的文档之间建立交叉链接：教程可以链接到相关参考页面；操作指南可以链接到背景说明
• 在所有类型的文档中使用一致的标题和术语，方便用户浏览整个文档体系

---

步骤 4 — 交付前进行验证

类型	验证项
教程	初学者能否在无需外部帮助的情况下从头到尾完成教程？
操作指南	是否为有经验的用户解决了所述问题？
参考资料	用户能否在 30 秒内找到特定信息？
说明	用户是否理解了原因，而不仅仅是内容？