title: “任务型 vs. 概念型”
description: “如何运用 Diátaxis 框架，把"How-To"指南与概念性解释区分开，构建更高效的文档结构。”

问题

技术写作中一个常见错误，是把"为什么这样做"与"具体怎么做"混在一起。例如，一篇"配置 SSO"的教程，可能被卷入好几页关于 SAML 协议历史的介绍。这会分散用户去完成眼前任务（让功能跑起来）的注意力。

为什么重要

用户的诉求差异很大。凌晨 2 点抢修生产事故的工程师，需要的是具体、可执行的步骤 —— 而不是架构哲学。反过来，正在评估您平台的技术负责人，必须先理解底层逻辑才能下定决心。把这两类内容分开，才能让两种角色都各取所需，避免无谓的摩擦。

方法

采用 Diátaxis 框架，它把文档划分为四个象限：教程 (Tutorials)、How-To 指南、解释 (Explanation/Concepts) 与技术参考。本指南重点关注 任务型内容（可执行的步骤）与 概念型内容（更深的理解）之间的关键切分。

实现

1. 任务型指南 (How-To)

完全聚焦于一个具体、单一的目标。砍掉冗长的理论解释，只保留达成目标所需的最少步骤。使用 Steps 容器 来提供清晰、明确的行动路径。

• 标题示例：“如何配置 Webhooks”
• 结构：
  • 前置条件
  • 直接、可执行的指令
  • 验证步骤（如何确认它真的生效）

2. 概念型指南 (Explanation)

聚焦于"大局观"：架构、设计哲学，以及具体决策背后的"为什么"。在这类段落里应避免直接的指令或命令。

• 标题示例：“理解 Webhook 投递架构”
• 结构：
  • 高层架构图
  • 重试逻辑与可靠性哲学
  • 安全考量

3. 有效的交叉引用

与其把两类内容揉在一起，不如借助 docmd 的链接工具架起桥梁，让需要更多背景、或准备动手的用户都能顺畅跳转。

• 在 How-To 指南中：“想深入了解我们的重试逻辑，请参阅 Webhook 架构。”
• 在概念指南中：“准备开始上手？请跟随我们的 Webhook 配置指南。”

取舍

把任务与概念拆开，会让导航里的页面变多，并要求严格的交叉链接。但这种模块化结构能显著提升整套文档的可维护性、可搜索性与整体专业度。