tutorial-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tutorial Design

教程设计

Design and write hands-on tutorials that transform complex technical concepts into engaging, progressive learning experiences with exercises, checkpoints, and troubleshooting guidance.

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

When to Use This Skill

何时使用此技能

Writing a getting-started tutorial for a library, API, or tool
Creating workshop materials for team training or conferences
Building multi-part learning series with progressive difficulty
Designing coding exercises with self-assessment checkpoints
Converting existing documentation into guided learning content
Creating quick-start guides that get users productive fast

为库、API或工具编写入门教程
为团队培训或会议创建研讨会材料
构建难度逐步提升的多部分学习系列
设计带有自我评估检查点的编码练习
将现有文档转换为引导式学习内容
创建能让用户快速上手的快速入门指南

Quick Reference

快速参考

Resource	Purpose	Load when
`references/design-patterns.md`	Progressive disclosure patterns, exercise types, checkpoint design, difficulty calibration, prerequisite mapping	Planning tutorial structure or designing exercises

资源	用途	加载时机
`references/design-patterns.md`	渐进式信息披露模式、练习类型、检查点设计、难度校准、前置知识映射	规划教程结构或设计练习时

Workflow Overview

工作流概述

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

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

Phase 1: Define Learning Objectives

阶段1：定义学习目标

Every tutorial starts with clear outcomes.

每篇教程都始于清晰的目标。

Opening Section Template

开篇模板

markdown

undefined

markdown

undefined

What You'll Learn

你将学到

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

[具体、可衡量的目标1]
[具体、可衡量的目标2]
[具体、可衡量的目标3]

Prerequisites

前置要求

[Required knowledge or setup]
[Tools needed]

[所需知识或环境配置]
[必备工具]

Time Estimate

时间预估

~[X] minutes

~[X] 分钟

What You'll Build

你将构建的成果

[Brief description or screenshot of the final result]


**Writing good objectives:**
- Use action verbs: "build", "configure", "debug", "deploy" — not "understand" or "learn about"
- Make them testable: the reader should be able to verify they achieved each outcome
- Scope realistically: 3-5 objectives per tutorial

---

[最终成果的简要描述或截图]


**撰写优质目标的要点：**
- 使用动作动词：“构建”、“配置”、“调试”、“部署”——而非“理解”或“了解”
- 确保可验证：读者应能确认自己是否达成每个目标
- 合理规划范围：每篇教程设置3-5个目标

---

Phase 2: Concept Decomposition

阶段2：概念拆解

Break the topic into atomic learning steps.

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

Sequencing Rules

排序规则

One concept per section — never introduce two new ideas at once
Dependency order — concepts must build on what came before
Concrete before abstract — show the working example, then explain the theory
Simple before complex — start with the minimal version, layer complexity

每个板块一个概念——切勿同时引入两个新知识点
依赖顺序——概念必须基于之前的内容逐步构建
先具象后抽象——先展示可运行示例，再解释理论
先简单后复杂——从最简版本开始，逐步增加复杂度

Concept Map

概念图谱

Before writing, sketch a dependency graph:

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

Each node becomes a section. Dependencies become the section order.

撰写前，绘制依赖关系图：

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

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

Phase 3: Design Exercises and Checkpoints

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

Exercise Types

练习类型

Type	Difficulty	When to use
Fill-in-the-blank	Low	Reinforce syntax after an example
Debug challenge	Medium	Teach error reading and common mistakes
Extension task	Medium	Add a feature to working code
From scratch	High	Build based on requirements only
Refactoring	High	Improve existing implementation

类型	难度	适用场景
填空题	低	示例后巩固语法
调试挑战	中等	教授错误解读和常见问题
拓展任务	中等	为可运行代码添加新功能
从零构建	高	仅基于需求完成构建
重构任务	高	优化现有实现

Checkpoint Pattern

检查点模式

After every major section, insert a checkpoint:

markdown

undefined

每个主要板块结束后，插入检查点：

markdown

undefined

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 section below.

undefined

此时你应已完成：

端口3000上运行的服务器
```
/health
```
端点返回
```
{ "status": "ok" }
```
服务器日志显示传入请求

若出现问题，请查看下方的故障排除板块。

undefined

Troubleshooting Sections

故障排除板块

For every section, anticipate 2-3 common errors:

markdown

undefined

为每个板块预判2-3个常见错误：

markdown

undefined

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.

---

错误：
EADDRINUSE: address already in use
其他进程正在使用端口3000。运行

lsof -i :3000

查找进程，然后停止该进程或更换端口。

错误：
Cannot find module 'express'
你尚未安装依赖项。在项目根目录运行

npm install

。

---

Phase 4: Write the Tutorial

阶段4：撰写教程

Section Structure (for each concept)

板块结构（每个概念对应一个板块）

Brief intro (1-2 sentences) — what this section covers and why it matters
Minimal example — complete, runnable code showing the concept
Line-by-line explanation — walk through the important parts
Try it — tell the reader to run the code and what to expect
Extend it — optional exercise to deepen understanding
Troubleshooting — common errors for this section

简要介绍（1-2句话）——说明本板块涵盖内容及重要性
最简示例——展示概念的完整可运行代码
逐行解释——讲解关键部分
动手尝试——指导读者运行代码并说明预期结果
拓展练习——可选练习以深化理解
故障排除——本板块的常见错误

Writing Principles

撰写原则

Show, then explain — code first, theory second
Frequent validation — readers should run code every 2-3 minutes
Fail forward — include intentional errors to teach debugging
Incremental complexity — each step adds one thing to the previous
Copy-paste friendly — examples must work when pasted directly

先展示后解释——先放代码，再讲理论
频繁验证——读者应每2-3分钟运行一次代码
从错误中学习——包含故意设置的错误以教授调试技巧
渐进式复杂度——每一步仅在之前基础上添加一项内容
便于复制粘贴——示例粘贴后即可直接运行

Content Elements

内容要素

Code blocks must:

Be complete and runnable (no
```
...
```
elisions in critical paths)
Include expected output in a separate block
Use meaningful variable names
Have inline comments only where non-obvious

Explanations should:

Connect to real-world use cases
Provide the "why" behind each step
Use analogies to familiar concepts
Anticipate the reader's "but what about...?" questions

代码块必须：

完整可运行（关键路径中无
```
...
```
省略）
在单独块中包含预期输出
使用有意义的变量名
仅在非显而易见处添加行内注释

解释应：

关联实际应用场景
说明每个步骤背后的原因
使用类比关联熟悉的概念
预判读者的“那如果……？”类问题

Closing Section

结尾板块

markdown

undefined

markdown

undefined

Summary

总结

You've learned how to:

[Outcome 1 restated]
[Outcome 2 restated]

你已学会如何：

[重述目标1]
[重述目标2]

Next Steps

下一步

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

---

[自然衔接的后续教程或主题]
[相关文档]
[社区资源]

---

Phase 5: Validate

阶段5：验证

Before publishing, test the entire tutorial path:

Follow every step from a clean environment
Run every code example and verify output matches
Trigger every troubleshooting scenario at least once
Time the tutorial — does it match the estimate?
Have someone unfamiliar with the topic attempt it

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

在干净环境中遵循每一步操作
运行所有代码示例并验证输出是否匹配
至少触发一次每个故障排除场景
计时教程——是否与预估时间相符？
让不熟悉该主题的人尝试完成教程

Tutorial Formats

教程格式

Format	Duration	When to use
Quick Start	5 min	First contact, get running fast
Deep Dive	30-60 min	Comprehensive single-topic exploration
Workshop Series	Multi-part	Progressive learning across sessions
Cookbook	Variable	Problem-solution pairs, non-linear reading
Interactive Lab	15-45 min	Hands-on environment with guided steps

格式	时长	适用场景
快速入门	5分钟	首次接触，快速上手
深度解析	30-60分钟	单主题全面探索
系列研讨会	多部分	跨场次渐进式学习
实战手册	不定	问题-解决方案配对，非线性阅读
交互式实验	15-45分钟	带引导步骤的实操环境

Anti-Patterns

反模式

Introducing concepts before they are needed ("you'll use this later")
Showing code snippets that cannot run standalone
Assuming knowledge not listed in prerequisites
Walls of text without code breaks
Exercises without solutions (even collapsed/hidden ones)
Skipping the "why" and only showing the "how"

提前介绍尚未用到的概念（“以后会用到”）
展示无法独立运行的代码片段
假设读者具备前置要求中未列出的知识
无代码间隔的大段文字
无解答的练习（即使是折叠/隐藏的解答也需要）
只讲“怎么做”而跳过“为什么”