教程把新手从零带到一个可运行的项目,一次给出一个可见结果,全部责任由作者承担。语气为引导性、直截了当、教育性、权威性。
当能力要求把产品的多个部分组装成一个真实项目,且这种价值只有在功能协同时才显现时,编写教程。它是构建和保持正确代价最高的类型,因此要有意识地选用。它不是:
- 快速入门。 快速入门在几分钟内证明产品可用;教程则通过大约一小时的有意义项目来培养能力。
- 如何操作。 如何操作服务于能自己推进的熟练读者;教程的读者一无所知,因此出了问题就是教程的责任。
- 概念课。 教程通过动手教学,而不是通过讲解。请链接概念,而不是展开概念。
完整对比请参阅内容类型。实例如 Workers 教程。
- 标题:第二人称祈使语气的短动词短语,按结果命名,例如 “Build an order-notification service”。不要使用 “Learn ...” 或 “Tutorial 1”。
- 描述:说明读者将构建什么,以及之后能够做什么,然后给出诚实的时间估计。
使用 Nimbus tutorial 模板生成此页面。你的编程代理会获取完整页面框架和自查清单,然后根据你的产品进行调整:
npx @cloudflare/nimbus-docs add content-tutorialyarn @cloudflare/nimbus-docs add content-tutorialpnpm @cloudflare/nimbus-docs add content-tutorial将模板生成的 frontmatter 调整为 Cloudflare 的 schema:设置 pcx_content_type 和 products,替代模板生成的 type 等通用字段。
- 步骤 或带编号的
##部分是骨架,每个部分都以逐字的 “You should see” 输出结束,以证明它成功了。绝不要跳过。 - 在读者实际会卡住的地方写的错误恢复正文 属于主路径内容,而不是异常标注框,因为在教程里,预见到的错误不是异常。
- GitHubCode 和 PackageManagers 让示例代码和安装命令保持固定版本并同步,ListTutorials 则在列表中展示该教程。
- 不适合放在这里的内容: 任何形式的选项卡和选项(作者已经选定唯一路径,按技术栈分开意味着按页分开)、冗长的概念旁白(改为外链),以及任何会隐藏步骤的内容。
pcx_content_type: tutorial
difficulty: Beginner
products:
- product-a
- product-b将 difficulty 设为 Beginner、Intermediate 或 Advanced,并用您上次从头到尾跑通教程的日期填写 reviewed。有关更多详细信息,请参阅 pcx_content_type。
教程是保持正确代价最高的类型,因为它必须对每一位读者、每一次、在一台冷机器上都成立;坏掉的教程会让新手以为产品本身坏了。少而新胜过多而旧,因此一篇经过测试的教程胜过五篇过时的。固定教程所依赖的每个版本,在每次发布时于干净环境中从头到尾重跑,并用该日期填写 reviewed。
- 部分自包含。 给每个部分完整语境的标题、完整命令和逐字结果,这样中途进入教程的读者或智能体知道自己在哪里,切勿使用“如上文所配置”这类位置性引用。
- 字面输出。 将每次预期输出放在围栏代码块中,使用完整、真实的值,因为这段 “You should see” 文本就是智能体和读者用来匹配的内容。
- 固定版本。 在前提条件中点明并固定每个版本,以免教程在最新发布中悄然失效。