Cognitive Load Management for Tutorials

Applying Cognitive Load Theory (Sweller) to tutorial design. The goal: maximize germane load (schema building) by minimizing extraneous load (bad design).

The Three Loads

Concept Budgeting

Each tutorial step has a concept budget of 3. A "concept" is any idea the reader must hold in working memory to complete the step.

Counting Concepts

Examples of what counts as one concept:

• A new CLI command and its primary flag
• A file format (e.g., PPM image format)
• An architectural pattern (e.g., middleware pipeline)
• A new API endpoint and its required parameters

Examples of what does NOT count (already in working memory for most developers):

• Running a command in a terminal
• Editing a file
• Standard Git operations
• Common data types (strings, lists, dicts)

When You Exceed the Budget

If a step requires 4+ concepts:

1. Split the step into two steps
2. Introduce concept N in step K, use it in step K+1
3. Provide a worked example that demonstrates multiple concepts together (reduces interactivity)

Worked Example Effect

Show complete working code first, then explain. Do not ask users to assemble code from descriptions.

Pattern:

Here is the complete handler:

\`\`\`python
{complete, working code}
\`\`\`

Let's break this down:
- Line 1-3: {what and why}
- Line 5: {what and why}

Anti-pattern:

First, import the handler module. Then create a function that
accepts a request parameter. Inside the function, validate the
input using... Now type this code:

\`\`\`python
{code}
\`\`\`

The anti-pattern forces the reader to build the code mentally from prose, then compare against the actual code -- double the cognitive load.

Split-Attention Avoidance

Code and its explanation must be co-located. Never separate them by more than a glance.

Good: Inline comments explaining non-obvious lines

token = jwt.encode(
    {"user_id": user.id, "exp": expiry},  # exp = auto-expiration
    SECRET_KEY,
    algorithm="HS256"  # HMAC-SHA256, sufficient for session tokens
)

Good: Explanation immediately after the code block, referencing specific lines

Bad: Code on one page, explanation on another Bad: "See the configuration reference for details on these options" Bad: Diagram with labels in a separate legend

Expertise Reversal Awareness

Detailed explanations help novices but slow experts. Address both:

1. Keep the main path lean (action -> verify)
2. Put detailed explanations in collapsible sections or "What just happened?" blocks
3. Offer a "fast track" callout for experienced readers: "Already familiar with JWT? Skip to Step 4."
4. Link to reference docs for readers who want depth, instead of inlining it

Scaffolding and Fading

Early steps provide more support. Later steps provide less.

• Step 1: Full code, detailed explanation, expected output, troubleshooting
• Step 3: Full code, brief explanation, expected output
• Step 5: Code with inline comments only, verification command
• Final step: "Now try adding {feature} on your own. Hint: use {function}."

This mirrors the Zone of Proximal Development: start within reach, gradually extend.

Chunking Patterns

Group related information into meaningful units:

• Command chunk: command + flags + expected output = one visual block
• Config chunk: file path + content + explanation = one visual block
• Concept chunk: term + one-sentence definition + example = one visual block

Use visual grouping (code blocks, callout boxes, headers) to reinforce chunks. Never scatter parts of the same chunk across multiple sections.