CLI 文档正在从 reference 页转向 runbook 结构

reference 页停得太早

经典 CLI 文档往往围绕命令、参数和示例来组织。这当然必要，但它经常在真实工作刚开始的时候就停住了。用户真正的问题通常不是“这个 flag 接收什么值”，而是“我该怎样完成一个任务、从失败中恢复，或者判断自己是不是处在正确状态里继续往下走”。

工具越深入部署、agent、云资源或团队工作流，单纯的命令 reference 就越不够用。

runbook 更贴合 CLI 工作

对很多命令行任务来说，runbook 是更合适的形状，因为它保留了顺序、分支和上下文。它解释的不只是“运行哪条命令”，还包括“什么时候运行”“应该看到什么输出”“哪里可能出错”“下一步应该做什么”。

这比单纯列出命令更贴近人们真正通过终端工作的方式。

好的 runbook 型文档通常会包含:

1. 前置条件。
2. 有顺序的命令路径。
3. 预期输出或检查点。
4. 恢复与回滚说明。

当命令不再是孤立小工具，而是更长的有状态流程的一部分时，这一点尤其重要。

文档与执行正在靠近

这种变化出现的另一个原因，是文档和执行本身正在靠近。浏览器演示、可复制命令块、会话历史、agent 建议和产品内引导，都在逐渐抹平“阅读”和“操作”之间的边界。

边界一旦模糊，文档就会被迫变得更 operational。一个只解释语法、却不帮助用户完成任务路径的页面，会越来越像不完整文档。

这并不是 reference 文档的消失，而是层级变化。reference 会继续存在，但真正承接用户完成工作的是 runbook 和面向任务的流程页。

好的结构应该完成什么

今天好的 CLI 文档，至少应该同时回答四层问题:

1. 有什么命令。
2. 它要求什么状态。
3. 它属于哪条任务路径。
4. 如果失败，应该怎么恢复。

这也是为什么围绕 CLI 工具写内容时，文档结构本身值得被纳入观察。文档已经不只是辅助材料，而是产品接口的一部分。当文档从 reference 转向 runbook 时，它其实也在暴露产品希望用户如何工作。