写或审计开发者教程时：用概念阶梯…

为开发者产品撰写或审计教学教程，使学习者从不会到能亲手构建并独立完成目标。

适用场景

解决思路

1. 先做范围确认：确认任务是教程，而不是 quickstart、how-to、reference、engineering blog、video script 或教育策略；若不符，转给对应技能，不要吸收请求。
2. 访谈时一次问一个问题，尽量多选；直到能说出学习目标和受众水平就停止，其余推断后确认。
3. 问：学习者之后能做什么现在不能做的事？要可演示能力，不是主题。
4. 问：他们会构建什么？给 2-3 个候选工件，选仍需要该概念的最小工件。
5. 问：受众水平：从未用过该产品 / 用过一次 quickstart / 有经验但新领域？
6. 问：可以假设他们已知道什么（语言、框架、协议、领域概念）？其余必须教、链接或删除。
7. 问：教程在哪个单一环境运行（语言、包管理器、OS、版本）？
8. 问：应该花多长时间？Good Docs Project 范围 15-60 分钟，超过则拆分。
9. 问：有伴随仓库、starter 项目或沙箱，还是从空目录开始？
10. 问：是全新写还是审计人们放弃的教程？
11. 问：谁能以学习者身份在什么机器上端到端运行完成的教程？
12. 问：页面必须在什么日期上线？硬日期让阶梯早一档停，并把指标推迟到流失视图之后。
13. 问：一次性胜利（下周发布需要页面）还是复合资产（文档集两年内基于此）？复合资产提升健壮性档、伴随仓库和 CI 运行检查点；一次性删除这三者。
14. 问：编写时间上限多少小时，谁每个发布拥有此页？没有指定所有者则删除 polish 档和伴随仓库。
15. 两个排名（阶梯停止档和 KPI 顺序）是默认而非法律；根据回答和团队已有情况重新排名；已有分析管道使流失视图近乎免费，已有沙箱使 real data 档近乎免费，任一提升都优于默认顺序。
16. 工作流：如果是审计，先让人冷启动跑现有教程收集真实放弃点，绝不只读着重写；如果是全新写，进入第2步。
17. 在起草任何内容前，用学习者执行的动词写学习目标句子；用 Good Docs Project 的措辞 "By the end of this tutorial, you'll be able to…" 后跟 design/assess/develop 等动词；如果无法测试他们能否做到，就不是目标。
18. 起草任何步骤前决定如何知道他们达到了：最终检查点，以及第11步中要求他们独立完成的变体；这防止阶梯漂移成产品巡览。
19. 选他们构建的工件：最小的、没有该概念就无法构建的东西；更大的项目增加打字而非学习。
20. 在顶部明确声明受众水平和前置条件：每行所需软件及检查命令，每项所需知识及链接；不要同时为两个水平写教程。
21. 构建概念阶梯：每步一个新概念，按依赖排序，其他复用；选停止档。
22. 起草步骤：每个步骤标题用祈使动词，完整意思（"Connect to the database" 而非 "Connect"），恰好一个动作；需要打开文件或屏幕时先定位。
23. 每个步骤包含：阶梯要求的代码形态、真实运行的期望输出、在步骤可能失败处的一行排错条目指针。
24. 每 3-5 步放置检查点（基线），每个是可验证状态和恢复点。
25. 写结尾：说明学习者现在能做什么，并在一处给出完整最终工件；然后指向 how-to guides（真实变体）、reference（机械）、explanation（为什么）。
26. 对散文（不是代码块）运行人类化润色，使其读起来像工程师在教学，而非模型叙述。
27. 用符合声明水平的真实学习者对照通过阈值验证；修复并重跑直到通过。
28. 埋点和记录：定义完成事件和每检查点流失视图；如果有持久记忆，存储学习目标、受众水平、选定环境和故意省略的概念，以便兄弟教程保持一致。
29. 概念阶梯按依赖排序，不按产品架构；每层端到端跑通再加下一层。
30. 阶梯层：Skeleton（最小可运行代码，有响应，每次发布维护近零）；Core concept（教程核心能力，承诺行为，每次破坏性变更约一小时）；Real data（自己的输入而非硬编码，fixtures/seed 脚本/沙箱随 schema 漂移）；Robustness（错误处理、验证，故意处理的失败，一个错误路径及期望输出，跨发布稳定）；Polish（配置、测试、结构，生产形态，持续工作，配置、锁文件、测试套件会腐烂）。
31. 行顺序是构建顺序；排名决定停止：价值 core concept > real data > robustness > polish；作者+维护成本 polish > real data > robustness > core concept > skeleton；效率 core concept > robustness > real data > polish。
32. 默认停止：core concept + robustness。当学习者的输入就是目标名称，或已有沙箱使 real data 档近乎免费时，上移到 real data。
33. 此顺序使 polish 饥饿；当教程兼作内部/企业工具 onboarding 且生产形态就是目标时，提升 polish；当访谈未指定页面所有者时，从计划删除 polish 档而非停在底部。
34. 两条规则保持阶梯教学：每步一个新东西；淡出指导。
35. 淡出指导：早期步骤给完整工作示例，后期步骤给更少，直到学习者自己产出代码；教程若第7步和第1步一样复制粘贴，就没教任何东西。
36. 三阶段指导淡出：Early 完整文件、所有导入、可粘贴运行；Middle 只给新增行、命名文件、说明插入点；Late 给需求加期望输出，答案一键之遥。
37. "一键之遥"绝不指一整块完成代码；分级揭示：1 指向相关参考页；2 伪代码；3 挖空有趣行的解决方案；4 完整解决方案。
38. 该编号是学习者走的升级路径，不是你写的顺序。只能写部分时按价值/编写小时排序：挖空方案 > 指针 > 完整方案 > 伪代码。
39. 挖空块是完整方案减三行，教得最多；指针是一个链接；完整方案粘贴免费，教得最少；伪代码是每次 API 变更都要重写的散文，说挖空块已说的东西。
40. 减去一切争夺学习者注意力的东西：未解释的 flag、第二个包管理器、重命名变量、杂散警告；通过 starter 仓库或脚手架命令预提供样板代码，打字不教任何东西。
41. 检查点三部分：产生可观察输出的命令或动作；确切的期望输出；不匹配时的恢复路线（排错条目或可恢复快照）。
42. 让每个检查点成为恢复点：伴随仓库中的分支或 tag、幂等 seed 脚本、或文档化的 "reset to step N"；学习者第二天回来从最后通过的检查点重新进入。
43. 伴随仓库分支与发布步骤漂移比没有仓库更糟；学习者信任代码胜过散文，会落入文本从未描述的状态。
44. 语言：写 "In this tutorial, we will…"，然后 "First, do x. Now, do y."；旅程用第一人称复数，动作用祈使。
45. 结果前设定期望："The output should look something like…"。
46. 引导否则会被错过的注意力："Notice that…", "Remember that…"。
47. 结尾肯定："You have built…"。
48. 不提供选择和替代方案；学习者在理解产品前必须解决的分支是停滞。
49. 解释保持一句话并链接出去；解释是最大诱惑，也是构建中途失去学习者的最快方式。
50. 故意跨步骤重复模式；重复有时是唯一老师。
51. 绝不把恢复行写成判决；不要 "You should have set the secret first"，而是命名状态："if the secret isn't set, this returns 401; set it and retry"。
52. 可取困难只用于必须保留的概念，且只在通过的检查点后作为可选、明确标记的添加，答案可用：预测输出再运行；故意破坏并读错误；扩展功能一个参数。
53. 因省略或模糊造成的困难不是可取困难；学习者会吸收为自己的失败并离开。
54. 受众上下文拆分：个体学习者、自助产品：前置可见结果；整个路径保持在免费层；最后检查点前不让账单提示出现。
55. 团队内部/企业工具 onboarding：第1步前列出所需访问及授予者；每个假定互联网的命令给离线/本地变体；添加可向审查者展示的检查点。
56. 通过阈值六条：1 每步真实输出匹配文档输出；2 每个检查点无需作者帮助通过；3 第1步后发现零前置条件；4 耗时在声明估计内且总体 15-60 分钟；5 学习者能在未走过的变体上独立再次完成目标；6 每个放弃或犹豫追溯到具体步骤并修复，不平均掉。
57. 第5条区分教程和长 quickstart；失败时说明阶梯淡出太晚或没淡出，学习者复制到工作应用。
58. KPI 默认：埋点前两个（transfer-test pass rate, per-checkpoint drop-off）并读第三个（support questions quoting a specific step）。
59. Transfer-test pass rate 来自冷运行（Level 2 Learning）：近乎零埋点，通过阈值第5条已运行，只记录结果；唯一在教程内证明技能形成而非粘贴应用。
60. Per-checkpoint drop-off（Level 1 Reaction）：约一小时，每检查点一个事件，检查点已存在；一个主要放弃检查点标记步骤坏了，先修步骤再围绕概念重写。
61. Support questions/issues quoting a specific step（Level 2 Learning）：近乎零收集，长期读取；每个定位错误或模糊指令到可修复句子。
62. Completion rate（Level 1 Reaction）：流失事件存在后免费；页面是否保持注意力，不说明是否学到。
63. Median completion time vs stated estimate（Level 1 Reaction）：免费；声明 30 分钟测出 70 分钟打破页面第一承诺；重测后重述。
64. Share of completers who perform same task in product within a week（Level 3 Behaviour）：长期工作；学习面和产品必须共享身份，发布前决定；完成而无产品内重复意味着教程教了教程而非产品。
65. KPI 排名：价值 behaviour share > transfer-test > per-checkpoint drop-off > support questions > completion rate == median time；埋点成本 behaviour share > support questions > per-checkpoint drop-off > completion rate == median time > transfer-test；效率 transfer-test > per-checkpoint drop-off > support questions > completion rate == median time > behaviour share。
66. 当教程算作激活步骤或需证明人头时，把 behaviour share 提升到一切之上；没有更便宜指标回答该问题，身份管道必须在发布前落地。
67. 不要从外部设数字目标；没有可信的开发者教程完成基准，与自身上一版比较。
68. 通过 CI 定期和提交时运行每个检查点的伴随分支对抗发布包，防止腐烂；教程在产品变更时坏，不是文档仓库变更时。
69. 识别三种形态：Greenfield（"Write a tutorial teaching…"）返回访谈然后按 outline template 起草页面；Audit（"Nobody finishes our…"）返回按步骤优先的缺陷列表然后重写失败步骤；Scope call（"Is this a tutorial or a how-to?"）返回分类、理由和拥有另一答案的兄弟技能。
70. Greenfield：按 references/tutorial-outline-template.md 逐节返回完整页面；绝不发布期望输出块是占位符的页面；如果无法运行命令，说明哪些块未验证并给作者运行列表。
71. Audit：返回表格，不是散文：步骤号、什么坏了、四种事件类型（defect, hidden prerequisite, concept gap, friction）、修复；按阻塞学习者数量排序，不按页顺序。
72. 两种模式：开始前确定学习目标和受众水平；猜测它们会产生功能巡览。
73. 失败模式修复：开头是架构或理论在第一个动作前 → 切到第一个动作，链接概念文档。
74. 一步引入两个新概念 → 拆分，每半有自己的可观察输出。
75. 最后一步还在复制粘贴 → 更早淡出：切换到 diff 块，然后到需求。
76. 教程按 OS、框架或包管理器分支 → 选一个，链接变体，保持分支在路径外。
77. 检查点说 "you should see something like this" 无确切输出 → 从真实运行粘贴真实输出。
78. 伴随仓库分支与步骤不匹配 → 从发布步骤重新生成分支，CI 测试每个。
79. 运行 90 分钟 → 在检查点拆成两个教程并声明顺序。
80. 所有人停在同一步骤 → 埋点，冷跑该步骤，修步骤而非周围散文。
81. 功能巡览伪装成教程 → 回到目标，删除每个不服务目标的步骤。
82. 同时为初学者和专家写 → 选一个水平，声明，链接另一受众别处。
83. 排错条目写成 "you should have…" → 改写责备式措辞；卡住的学习者读作对自己的判决并关闭标签页。
84. 把本技能阈值当作行业标准引用给团队 → 引用前检查 references/published-findings.md；这里大多数数字是自设基线。

适用边界 · 注意事项

• 不用于 quickstart：目标是一次快速证明产品可用，没有技能转移。
• 不用于 how-to 指南：读者已有技能，想完成具体现实任务，且需要按自身情况分支；不要吸收这种请求。
• 不用于 API 参考、工程博客、录制视频脚本或教育策略问题；这些应转给对应技能。