问题

技术文档常常密集、术语多、难以扫读。当读者面对一堵没有任何视觉喘息的"文字墙"时，他们会略过关键细节。密集的排版会抬升认知摩擦，导致用户沮丧并引发潜在错误。

为什么重要

可读性是一项功能性需求。一旦开发者漏掉了埋在长段落中的警告，后果可能很严重。清晰的信息层级能保证用户快速找到信息、准确理解，并安全采取行动。

方法

把长段落打散，建立可预测的视觉节奏；用 主题容器 突出关键信息。借助 docmd 内置的结构工具构建层级，让读者的视线自然落到页面最重要的部分。

实现

1. “简洁的力量”

把段落控制在三到四句话以内。短段落更易于在屏幕上消化，也为复杂的技术概念提供了"呼吸空间"。如果某段显得过长，请拆成列表或使用子标题。

2. 使用标注进行分类

坚持用 标注 (Callout) 对信息分类。这样，扫读型的读者可以凭借视觉样式判断一段内容的意图：

• Info：背景上下文或补充细节。
• Tip：最佳实践、捷径、“小贴士”。
• Warning/Danger：可能导致错误、数据丢失或安全漏洞的关键操作。

::: callout warning "生产安全"
    在没有事先确认备份前，请勿在生产数据库上执行此命令。
:::

3. 使用 Steps 承载顺序性指令

对于教程，请避免用叙述形式描述操作步骤。改用 Steps 容器 来呈现清晰、带编号的推进过程。

::: steps
    1. **初始化**：在项目根目录运行 `npx @docmd/core init`。
    2. **配置**：更新 `docmd.config.json`，填入站点标题与导航。
    3. **构建**：运行 `npx @docmd/core build`，生成可直接上线的静态文件。
:::

取舍

使用 ::: steps、::: callout 这类专用容器，需要贡献者学习 docmd 特定的 Markdown 扩展。虽然会引入一点点学习曲线，但信息密度与清晰度上的显著提升，远远覆盖这层极小的成本。