Tutorial Design

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

Quick Reference

---

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: Define Learning Objectives

Every tutorial starts with clear outcomes.

Opening Section Template

## 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]

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

---

Phase 2: Concept Decomposition

Break the topic into atomic learning steps.

Sequencing Rules

1. One concept per section — never introduce two new ideas at once 2. Dependency order — concepts must build on what came before 3. Concrete before abstract — show the working example, then explain the theory 4. 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.

---

Phase 3: Design Exercises and Checkpoints

Exercise Types

Checkpoint Pattern

After every major section, insert a checkpoint:

### 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.

Troubleshooting Sections

For every section, anticipate 2-3 common errors:

### 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.

---

Phase 4: Write the Tutorial

Section Structure (for each concept)

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

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

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

## Summary

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

## Next Steps

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

---

Phase 5: Validate

Before publishing, test the entire tutorial path:

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

---

Tutorial Formats

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"

Tutorial Design Patterns Reference

Progressive disclosure patterns, exercise types, checkpoint design, difficulty calibration, prerequisite mapping, and troubleshooting section design.

---

Progressive Disclosure Patterns

Pattern 1: Minimal Viable → Full Feature

Start with the smallest working version, then layer features:

Step 1: Hello World (just prove it runs)
Step 2: Accept input (add one parameter)
Step 3: Validate input (add error handling)
Step 4: Persist results (add storage)
Step 5: Add UI (add presentation layer)

Each step produces a working result. Readers can stop at any step and have something useful.

Pattern 2: Concrete → Abstract

Show the specific case first, then generalize:

Step 1: Hard-code a specific example
Step 2: Replace hard-coded values with variables
Step 3: Extract into a reusable function
Step 4: Discuss when to use the pattern

Pattern 3: Happy Path → Edge Cases

Get the basic case working before handling complexity:

Step 1: Handle the normal case
Step 2: What if input is empty?
Step 3: What if the network fails?
Step 4: What about concurrent access?

Pattern 4: Visual → Code → Theory

For concept-heavy topics:

Step 1: Diagram showing what happens
Step 2: Code that implements it
Step 3: Explanation of why it works
Step 4: When to use (and not use) this approach

---

Exercise Types

Fill-in-the-Blank

Purpose: Reinforce syntax and patterns just introduced.

Template:

### Exercise: Complete the middleware

Fill in the blanks to create an authentication middleware:

\`\`\`javascript
function authMiddleware(req, res, next) {
  const token = req.headers[______];  // 1. Which header?

  if (!token) {
    return res.status(______).json({   // 2. Which status code?
      error: "Authentication required"
    });
  }

  try {
    const decoded = jwt.verify(token, ______);  // 3. What to verify against?
    req.user = decoded;
    next();
  } catch (err) {
    return res.status(______).json({   // 4. Which status code for invalid token?
      error: "Invalid token"
    });
  }
}
\`\`\`

<details>
<summary>Solution</summary>

1. `'authorization'`
2. `401`
3. `process.env.JWT_SECRET`
4. `403`

</details>

Debug Challenge

Purpose: Teach error reading and common mistakes.

Template:

### Exercise: Fix the bug

This code should fetch user data, but it fails silently. Find and fix the issue:

\`\`\`javascript
// BUG: This function never returns the user data
async function getUser(id) {
  const response = fetch(`/api/users/${id}`);
  const data = response.json();
  return data;
}
\`\`\`

**Hints**:
1. Check what `fetch` returns...
2. What keyword is missing?

<details>
<summary>Solution</summary>

Missing `await` on both async operations:
\`\`\`javascript
async function getUser(id) {
  const response = await fetch(`/api/users/${id}`);
  const data = await response.json();
  return data;
}
\`\`\`

</details>

Extension Task

Purpose: Build confidence by adding to working code.

Template:

### Exercise: Add pagination

The API currently returns all results. Add pagination support:

**Requirements**:
- Accept `page` and `limit` query parameters
- Default to page 1, limit 20
- Return total count in the response
- Return next/previous page links

**Starting code**: Use the server from the previous section.

**Hints**:
1. `req.query.page` gives you the query parameter
2. SQL: `LIMIT ? OFFSET ?`
3. Offset = (page - 1) * limit

From Scratch

Purpose: Verify the reader can apply concepts independently.

Template:

### Exercise: Build a rate limiter

Using what you've learned about middleware and Redis, build a rate limiter that:

- Limits each IP to 100 requests per minute
- Returns 429 Too Many Requests when exceeded
- Includes a `Retry-After` header

**No starter code provided.** Refer back to the middleware and Redis sections if needed.

Refactoring

Purpose: Teach code improvement and design thinking.

Template:

### Exercise: Refactor for testability

This function works but is hard to test because it directly calls the database:

\`\`\`javascript
async function createUser(name, email) {
  const db = require('./database');
  const existing = await db.query('SELECT id FROM users WHERE email = ?', [email]);
  if (existing.length > 0) throw new Error('Email taken');
  return db.query('INSERT INTO users (name, email) VALUES (?, ?)', [name, email]);
}
\`\`\`

Refactor it so the database dependency can be injected for testing.

---

Checkpoint Design

When to Insert Checkpoints

• After every major concept introduction
• After every exercise
• Before moving to a new topic area
• At natural "save points" where progress is visible

Checkpoint Template

### Checkpoint

At this point you should have:
- [ ] [Concrete, verifiable state 1]
- [ ] [Concrete, verifiable state 2]
- [ ] [Concrete, verifiable state 3]

**Verify it works**:
\`\`\`bash
[command to run that shows success]
\`\`\`

**Expected output**:
\`\`\`
[exact output the reader should see]
\`\`\`

> **Something wrong?** Check the [Troubleshooting](#troubleshooting) section,
> or compare your code against the [checkpoint snapshot](link).

Checkpoint Principles

• Observable: The reader should see concrete evidence of progress
• Reversible: If the checkpoint fails, the reader knows where to look
• Quick: Verification should take seconds, not minutes
• Binary: Either it works or it doesn't — no ambiguity

---

Difficulty Calibration

Difficulty Levels

Calibration Rules

1. State the level — tell readers upfront who this is for 2. One level per tutorial — do not mix beginner and advanced in one doc 3. Prerequisites bridge levels — "This tutorial assumes you completed the Getting Started guide" 4. Explicit vs implicit steps:

• Beginner: "Open your terminal. Type npm init -y and press Enter."
• Intermediate: "Initialize a new Node project with npm init -y."
• Advanced: "Scaffold the project (we'll assume standard Node tooling)."

Pacing Guide

---

Prerequisite Mapping

Prerequisite Types

Prerequisite Documentation Template

## Prerequisites

### Required Knowledge
- [ ] JavaScript ES6+ (arrow functions, destructuring, async/await)
- [ ] Basic HTTP concepts (methods, status codes, headers)

### Required Setup
- [ ] Node.js 18 or later ([install guide](link))
- [ ] A code editor (VS Code recommended)
- [ ] A terminal (any shell)

### Required Accounts
- [ ] GitHub account ([sign up](link))

### Prior Tutorials
- [ ] [Getting Started with Express](link) — we build on the server from this tutorial

Prerequisite Verification

Where possible, give commands to verify prerequisites:

Verify your setup before starting:

\`\`\`bash
node --version    # Should output v18.x or higher
npm --version     # Should output 9.x or higher
git --version     # Should output 2.x or higher
\`\`\`

---

Troubleshooting Section Design

Structure

Place troubleshooting at the end of each major section and a consolidated version at the end of the tutorial.

Entry Format

**Error: `ECONNREFUSED: connect ECONNREFUSED 127.0.0.1:5432`**

The database server is not running.

**Fix**:
\`\`\`bash
# macOS (Homebrew)
brew services start postgresql

# Linux (systemd)
sudo systemctl start postgresql

# Docker
docker start my-postgres-container
\`\`\`

**Still not working?** Check that PostgreSQL is configured to accept local connections
in `pg_hba.conf`.

Common Error Categories

Troubleshooting Principles

1. Show the exact error message — readers search by error text 2. Explain why it happens — not just how to fix it 3. Provide the fix command — copy-paste ready 4. Include a fallback — "If that doesn't work, try..." 5. Link to deeper resources — for complex issues beyond tutorial scope