问题

技术写作中常见的一个错误是将“为什么要这样做”与“如何具体操作”混为一谈。例如，一个关于“配置 SSO”的教程，很容易因为大篇幅解释 SAML 协议的历史而变得冗长乏味，分散了用户实现功能这一首要目标的注意力。

为什么重要

用户的意图会根据其当前所处的上下文而有很大差异。凌晨 2 点试图修复生产问题的工程师寻找的是具体、可操作的步骤，而不是架构哲学。相反，正在评估您平台的技术负责人则需要在投入实施之前理解其背后的逻辑。分离这些关注点可以确保这两类角色都能在没有不必要干扰的情况下找到所需的信息。

方法

采用 Diátaxis 框架，它将文档分为四个不同的象限：教程 (Tutorials)、操作指南 (How-to Guides)、解释 (Explanation/Concepts) 和技术参考 (Technical Reference)。在本指南中，我们专注于任务导向型内容（可操作步骤）与概念导向型内容（深入理解）之间的关键分离。

实施

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

完全专注于一个具体、明确的目标。删掉冗长的理论解释，专注于实现该目标所需的最少步骤。使用 步骤容器 (Steps Container) 提供清晰、无歧义的路径。

• 标题示例：“如何配置 Webhook”
• 结构：
  • 前提条件
  • 直接、可操作的说明
  • 验证步骤（如何知道操作已成功）

2. 概念导向型指南 (Explanation)

专注于“大局”，包括架构、设计哲学以及特定决策背后的“原因”。在这些部分中，避免提供直接的指令或命令。

• 标题示例：“理解 Webhook 交付架构”
• 结构：
  • 高层架构图
  • 重试逻辑与可靠性哲学
  • 安全注意事项

3. 有效的交叉引用

不要合并这两类内容，而是使用 docmd 的链接工具为需要更多上下文或准备实施的用户提供桥梁。

• 在操作指南中：“有关我们重试逻辑的深入探讨，请参阅 Webhook 架构。”
• 在概念指南中：“准备好开始了吗？请遵循我们的 Webhook 配置指南。”

权衡

将任务与概念分离开来会增加导航中的页面数量，并需要更严格的交叉引用规范。然而，这种模块化结构显著提高了文档套件的长期可维护性、可搜索性以及整体专业性。