tutorial-design

教程设计

设计并编写动手实践教程，将复杂的技术概念转化为引人入胜、循序渐进的学习体验，并包含练习、检查点和故障排查指南。

何时使用此技能

• 为库、API 或工具编写入门教程
• 为团队培训或会议制作研习材料
• 构建难度循序渐进的多部分学习系列
• 设计带有自我评估检查点的编程练习
• 将现有文档改编为引导式学习内容
• 创建帮助用户快速上手的快速入门指南

快速参考

资源	用途	在何时加载
references/design-patterns.md	渐进式信息呈现模式、练习类型、检查点设计、难度校准、先决条件映射	规划教程结构或设计练习时

---

工作流概览

Phase 1: Objectives   → Define learning outcomes, prerequisites, and audience
Phase 2: Decompose    → Break concepts into atomic, sequenced steps
Phase 3: Design       → Create exercises, checkpoints, and troubleshooting tips
Phase 4: Write        → Produce tutorial content with runnable examples
Phase 5: Validate     → Test the tutorial path end-to-end

---

阶段 1：定义学习目标

每篇教程都从明确的学习成果开始。

开篇章节模板

## What You'll Learn

- [Specific, measurable outcome 1]
- [Specific, measurable outcome 2]
- [Specific, measurable outcome 3]

## Prerequisites

- [Required knowledge or setup]
- [Tools needed]

## Time Estimate

~[X] minutes

## What You'll Build

[Brief description or screenshot of the final result]

编写优质目标：

• 使用行动动词：“构建”“配置”“调试”“部署”，而不是“理解”或“了解”
• 确保目标可测试：读者应能验证自己是否达成了每项成果
• 合理设定范围：每篇教程设置 3-5 个目标

---

阶段 2：分解概念

将主题拆解为原子化的学习步骤。

排序规则

1. 每节一个概念——一次只引入一个新想法
2. 按依赖关系排序——后续概念必须建立在前面内容的基础上
3. 先具体后抽象——先展示可运行的示例，再解释理论
4. 先简单后复杂——从最精简的版本开始，逐步增加复杂度

概念图

写作前，先绘制依赖关系图：

[Prerequisites] → [Core concept A] → [Core concept B]
                                    ↘ [Variation 1]
                  [Core concept A] → [Core concept C] → [Advanced topic]

每个节点对应一节。依赖关系决定章节顺序。

---

阶段 3：设计练习和检查点

练习类型

类型	难度	使用时机
填空题	低	示例之后巩固语法
调试挑战	中	学习阅读错误信息和避免常见错误
扩展任务	中	为可运行的代码添加功能
从零开始	高	仅依据需求进行构建
重构	高	改进现有实现

检查点模式

每个主要章节之后都插入一个检查点：

### Checkpoint

At this point you should have:
- [ ] A running server on port 3000
- [ ] The `/health` endpoint returning `{ "status": "ok" }`
- [ ] Server logs showing incoming requests

**If something's wrong**, see the [Troubleshooting](#troubleshooting) section below.

故障排查章节

针对每一节，预判 2-3 个常见错误：

### Troubleshooting

**Error: `EADDRINUSE: address already in use`**
Another process is using port 3000. Run `lsof -i :3000` to find it,
then stop it or change your port.

**Error: `Cannot find module 'express'`**
You haven't installed dependencies yet. Run `npm install` in the project root.

---

阶段 4：撰写教程

章节结构（适用于每个概念）

1. 简短介绍（1-2 句话）——说明本节涵盖的内容及其重要性
2. 最简示例——提供展示该概念的完整可运行代码
3. 逐行说明——讲解重要部分
4. 动手试试——让读者运行代码，并说明预期结果
5. 拓展练习——可选练习，帮助加深理解
6. 故障排查——本节的常见错误

写作原则

• 先展示，再解释——先给出代码，再讲解理论
• 频繁验证——读者每隔 2-3 分钟就应运行一次代码
• 在失败中前进——加入有意设置的错误来教授调试
• 循序渐进地增加复杂度——每一步只在上一步的基础上增加一项内容
• 便于复制粘贴——示例直接粘贴后必须可以运行

内容要素

代码块必须：

• 完整且可运行（关键部分不得用 ... 省略）
• 在单独的代码块中提供预期输出
• 使用有意义的变量名
• 仅在不易理解的地方添加行内注释

讲解应当：

• 联系实际应用场景
• 解释每个步骤背后的“原因”
• 使用读者熟悉的类比
• 预先解答读者可能提出的“但是……呢？”问题

结尾章节

## Summary

You've learned how to:
- [Outcome 1 restated]
- [Outcome 2 restated]

## Next Steps

- [Natural follow-on tutorial or topic]
- [Related documentation]
- [Community resources]

---

阶段 5：验证

发布前，请测试完整的教程流程：

1. 在干净的环境中按照每个步骤操作
2. 运行每个代码示例并验证输出是否匹配
3. 至少触发每种故障排查场景一次
4. 记录教程所需时间——是否符合预估？
5. 请一位不熟悉该主题的人尝试

---

教程形式

形式	时长	适用场景
快速入门	5 min	初次接触，快速运行起来
深入探索	30-60 min	全面探索单个主题
系列工作坊	多部分	跨多个课程逐步学习
食谱集	不定	问题与解决方案配对，非线性阅读
交互式实验	15-45 min	在引导步骤下动手实践

反模式

• 在概念尚未用到时就介绍它们（“稍后你会用到这个”）
• 展示无法独立运行的代码片段
• 假设读者掌握了前置条件中未列出的知识
• 大段文字之间没有代码示例打断
• 提供没有答案的练习（即使答案折叠或隐藏也不行）
• 只展示“怎么做”，却跳过“为什么”