问题

在产品的早期阶段，记录一个功能可能只需要几个段落。然而，随着产品演变为企业平台，这些段落可能会激增，变成充斥着边缘案例、平台特定变体（Docker、Kubernetes、Cloud）以及复杂配置选项的海洋。这会导致“垂直膨胀”，即单页面变成难以阅读、难以导航且难以维护的文字墙。

为什么这很重要

垂直膨胀会破坏理解并增加认知负荷。当用户被迫滚动浏览大量与其特定环境或用例无关的内容时，他们会感到不知所措，并往往认为产品比实际情况更复杂。可扩展的写作可确保用户在任何特定时刻只看到他们需要的信息，从而保持一条清晰的成功之路。

方法

实施 渐进式披露 (Progressive Disclosure)。这种技术涉及预先仅呈现最关键的信息（“快乐路径”），并将更复杂、技术性更强或更具体的细节隐藏在交互式 UI 结构后面。docmd 提供了几种专门设计的内置容器，可帮助你有效且优雅地管理这种复杂性。

实现

1. 使用选项卡处理变体

与其按顺序罗列多个包管理器、操作系统或云提供商的说明，不如使用 选项卡容器。这允许用户选择他们的特定环境，即时隐藏无关的命令并减少视觉噪音。

::: tabs

    == tab "npm"
        ```bash
        npm install docmd
        ```

    == tab "pnpm"
        ```bash
        pnpm add docmd
        ```
:::

2. 使用折叠区块管理边缘案例

如果一个故障排除步骤或特定的边缘案例仅适用于极少数用户，请不要让它中断主教程的逻辑流程。使用 折叠容器 来埋没这些细节，同时在需要时保持它们易于访问。

1. 通过运行 `npx @docmd/core dev` 启动开发服务器。

::: collapsible "故障排除：端口已被占用"
如果你收到 `EADDRINUSE` 错误，可以使用 `--port` 标志指定自定义端口：`npx @docmd/core dev --port 4000`。
:::

3. 使用标注提供渐进式细节

使用 标注 提供补充信息，这些信息虽然不是主要任务所必需的，但能为高级用户提供有价值的上下文。

权衡

将内容隐藏在选项卡或折叠区块中偶尔会使用户更难使用浏览器的原生 Ctrl+F 搜索来查找信息。然而，docmd 集成的 搜索引擎 会对这些容器内的所有内容进行索引，从而确保用户在享受更整洁的阅读体验的同时，仍能通过网站的主搜索界面准确找到他们需要的内容。