问题

在产品的早期阶段，记录一个功能可能只需要几个段落。然而，随着产品演变为企业级平台，这些段落可能会迅速膨胀为大量的边缘案例、特定平台的变体（Docker、Kubernetes、云端）以及复杂的配置选项。这会导致“纵向膨胀”，即单个页面变成了一面难以阅读的文字墙，且难以导航和维护。

为什么重要

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

方法

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

实施

1. 使用选项卡处理变体

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

::: tabs
::: tab "npm"
```bash
npm install docmd

:::
::: tab “pnpm”

pnpm add docmd

:::
:::

### 2. 使用可折叠部分管理边缘案例

如果故障排除步骤或特定边缘案例仅适用于极少数用户，请不要让它中断主教程的逻辑流。使用 [可折叠容器 (Collapsible Container)](../../content/containers/collapsible) 埋没这些细节，同时在需要时保持其易于访问。

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

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

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

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

权衡

将内容隐藏在选项卡或可折叠部分中，偶尔会使用户更难使用浏览器的原生 Ctrl+F 搜索来查找信息。然而，docmd 集成的 搜索引擎 会索引这些容器内的所有内容，确保用户仍然可以通过站点的首要搜索界面准确找到他们需要的内容，同时享受更清爽的阅读体验。