操作指南

任务页面的指南——带编号的步骤，将有能力的读者从目标带到已验证的结果。包含清单和搭建命令。

更新于 Sep 30, 2026查看 Markdown

何时使用

当存在一个目标、一个结果、且读者有能力遵循指示时使用操作指南。它不是：

教程。 教程通过构建来教学；作者全程引导，不允许出错。操作指南服务于正在工作中自行推进的读者。如果页面必须对什么都不懂的读者有效，写教程。
参考。 如果读者在查找一个值、一个选项或一个限制——而非执行一系列操作——那是参考。操作指南链接到参考；从不内联完整的选项表。
概念。 当你开始用超过一句话解释为什么产品这样运作时，删掉并链接到概念页面。步骤中间的解释是读者迷失位置的地方。

每个页面一个目标。“轮换签名密钥”和“撤销签名密钥”是两个页面，而非一个页面的两半。注意那些将多个目标偷渡过此测试的伞状动词——“管理密钥”和“配置白名单”各自隐藏了创建、修改和删除。

标题和描述

标题：陈述目标的祈使动词短语。 “轮换签名密钥。” “添加第二个端点。” 不用动名词（“Rotating secrets”），不用裸名词（“Secret rotation”），不要加 “How to” 前缀——祈使动词短语本身就是类型的信号。
描述公式： “动词 + 对象，附带收益或关键约束。”——例如 “轮换签名密钥而不丢失投递。两个密钥在重叠窗口期内都保持有效。”

搭建此页面

安装指南——你的编码智能体会读取完整的骨架和清单，并将其适配到你的产品：

npx @cloudflare/nimbus-docs add content-how-to

yarn dlx @cloudflare/nimbus-docs add content-how-to

pnpm dlx @cloudflare/nimbus-docs add content-how-to

bunx @cloudflare/nimbus-docs add content-how-to

组件指导

带编号的步骤是定义性结构——作为 Steps 组件或普通有序列表；两者在 .md 版本中必须读起来相同。如果一个页面没有步骤，质疑它是否是操作指南。
Tabs / 代码组在一个规范页面内承载变体维度（语言、平台、CLI vs 控制台）。按变体复制页面是失败模式。对于替代方法，不要用标签页——选择推荐的那个并链接其余的。
提示框： 在破坏性步骤之前发出警告（正常路径的一部分），以及正常路径的例外（“如果你使用的是旧版计划……”）。一个被例外提示淹没的操作指南说明正常路径选错了。
不适用： Cards（此页面在 Next steps 之前不导航到任何地方）、冗长的概念旁白、完整选项表（链接到参考）。

结尾

固定页脚，按顺序：验证 → 不可逆的收尾步骤（如果任务有的话）→ 可选块 → 后续步骤 包含 2–4 个精选链接。永远不要在最后一个编号步骤结束——停在步骤 6 的页面会让读者不确定自己是否完成了。

阈值

每个阶段 ≤ ~10 个步骤。 较长的单目标流程用 ### 划分阶段；目标成倍增长的页面需要拆分。测试标准是标题：如果需要“和”，那是两个页面。
上下文介绍 ≤ 2 句。 更长意味着概念内容渗入了。
一个目标。 伞状动词（“管理 X”）是多个目标的标志。

链接和新鲜度

向外链接以获取深度：概念解释为什么，参考提供数值，相邻操作指南告诉你下一步。最小化步骤内的链接——步骤中的每个链接都是一个出口匝道。每当功能变更时，对照实际产品重新验证步骤，并记录结果（frontmatter 中的 lastVerified 日期或等效方式），使过时状态可见而非事后发现——一个步骤已漂移的操作指南比没有页面更糟，因为错误的步骤会主动误导，而缺失的页面只是令人失望。

智能体备注

每个步骤必须脱离周围页面也能独立执行：命名产品区域、完整命令、确切设置标签——永远不要写“如上所述配置”。
将预期输出放在围栏块中，使用完整、真实的值——不要用 … 截断凭据；智能体会匹配你展示的内容。
标签页变体在 .md 版本中必须展平为带标签的章节；永远不要让步骤的唯一副本活在会丢弃内容的组件内。
验证章节同时充当智能体的验收检查——写成可执行的内容，并明确失败分支。

清单

建议性——供作者自查或智能体最终审查，不是构建门禁：