instructional-design-writing

Instructional Design Writing

Transform information into learning. This skill provides the principles and frameworks instructional designers use to create content that enables skill transfer and behavior change.

Core Philosophy

The Goal: Enable the learner to do something they couldn't do before. Not to impress them with your knowledge—to transfer capability.

The Test: After reading, can they perform the task without additional help?

The Principle: Learning is not reading. Learning is practice with feedback.

The Jobs to Be Done

An instructional designer serves multiple functions:

Role	Core Job	Key Question
Learning Architect	Design the path from novice to competent	What's the most efficient sequence?
Cognitive Load Manager	Prevent overwhelm	How much is too much at once?
Practice Designer	Create opportunities to apply knowledge	Where do they practice before real stakes?
Assessment Builder	Verify transfer happened	How do we know they can do it?
Motivation Engineer	Sustain engagement through difficulty	Why should they keep going?
Error Anticipator	Predict and address failure points	Where will they get stuck?

Foundational Frameworks

1. Bloom's Taxonomy (Revised)

Levels of cognitive skill, from simple to complex. Design for the level required by the task.

Level	Description	Verbs	Example
Remember	Recall facts	Define, list, name, identify	"Name the HTTP status codes"
Understand	Explain meaning	Describe, explain, summarize	"Explain why 404 differs from 500"
Apply	Use in new situations	Execute, implement, use	"Configure a custom 404 page"
Analyze	Break into parts	Compare, contrast, debug	"Debug why this returns 500"
Evaluate	Judge and justify	Critique, assess, recommend	"Recommend the best error handling strategy"
Create	Produce new work	Design, construct, develop	"Design a comprehensive error handling system"

Key Insight: Most technical documentation targets Remember/Understand when users need Apply/Analyze. Design for the level that matches real tasks.

2. Cognitive Load Theory

Working memory is limited (~4 items). Manage the load:

Load Type	Description	Strategy
Intrinsic	Complexity inherent to the topic	Sequence from simple to complex
Extraneous	Complexity from poor design	Eliminate unnecessary steps, jargon
Germane	Effort toward schema building	Provide worked examples, patterns

Practical Application:

• Chunk information (max 5-7 items per section)
• Use consistent terminology
• Eliminate decorative elements
• Build on prior knowledge explicitly
• Provide worked examples before asking for practice

3. The 4C/ID Model

Four components for complex skill learning:

1. Learning Tasks: Whole, meaningful tasks in sequence of difficulty
2. Supportive Information: Explains the "why" and mental models
3. Just-in-Time Information: Procedural steps needed during task
4. Part-Task Practice: Isolated drill for automated skills

Example Application (Learning Git):

Component	Content
Learning Tasks	"Push a change to a shared repo" → "Resolve a merge conflict" → "Rebase and clean history"
Supportive Information	"Git tracks changes as snapshots, not diffs..."
Just-in-Time	"Run git status to see staged changes"
Part-Task Practice	Typing common commands until automatic

Structural Patterns

Pattern 1: Prerequisites → Concept → Procedure → Practice

The fundamental tutorial structure.

## Prerequisites
[What they must know/have before starting]

## What You'll Learn
[Outcome statement: After this, you'll be able to...]

## Why This Matters
[Motivation: When you'll use this, what problem it solves]

## Core Concept
[Mental model explanation, 2-3 paragraphs max]

## Step-by-Step Procedure
[Numbered steps, one action per step]

## Try It Yourself
[Practice exercise with clear success criteria]

## Common Mistakes
[Anticipated errors with corrections]

## Summary
[Key points, 3-5 bullets]

## Next Steps
[Where to go from here]

Pattern 2: Problem → Solution → Explanation

For troubleshooting guides and fix-it content.

## Problem
[Exact symptoms the user experiences]
[Error messages they might see]

## Quick Fix
[Fastest solution for most cases]

## Verify It Worked
[How to confirm the fix succeeded]

## Why This Happened
[Explanation for those who want to understand]

## Prevention
[How to avoid this in the future]

Pattern 3: Before → After → How

For transformation-focused content.

## Before
[Current state, pain points, limitations]

## After
[Desired state, benefits, capabilities]

## How
[Step-by-step transformation path]

Writing Techniques

1. Learning Objectives

Write objectives that are:

• Specific: Observable, measurable behavior
• Action-oriented: Use strong verbs from Bloom's
• Bounded: Clear scope of what's included/excluded

Weak: "Understand Git" Strong: "Create a branch, make changes, and open a pull request"

Weak: "Learn about APIs" Strong: "Authenticate with OAuth 2.0 and make a paginated GET request"

2. Chunking

Break content into digestible units:

• One idea per paragraph
• One action per step
• One concept per section
• Max 5-7 items in any list

Too Dense:

"First you need to initialize the repo with git init, then stage your changes with git add which moves files to the staging area, and then commit with git commit -m including a message, making sure the message is descriptive..."

Chunked:

1. Initialize the repository: git init
2. Stage your changes: git add [files]
3. Commit with a message: git commit -m "Your message"

3. Worked Examples

Show the complete solution before asking for practice:

## Worked Example

**Task**: Create an API endpoint that returns user data.

**Step 1**: Define the route
[Code with comments explaining each line]

**Step 2**: Add the handler function
[Code with comments]

**Step 3**: Test the endpoint
[Command with expected output]

## Now Try It
Create a similar endpoint for products. Success criteria:
- GET /products returns JSON array
- Each product has id, name, price
- Test passes with curl command

4. Scaffolding

Provide support that decreases as competence grows:

Stage	Support Level
First try	Complete worked example to follow
Second try	Partial example, fill in the blanks
Third try	Prompt only, no example
Fourth try	Novel problem, transfer required

5. Error Anticipation

Predict where learners will fail and address proactively:

## Common Mistakes

**Mistake**: Running `git push` before `git commit`
**Symptom**: "Everything up-to-date" but changes not visible
**Fix**: Check `git status`. If changes are staged, commit first.

**Mistake**: Forgetting to pull before push
**Symptom**: "Updates were rejected because the remote contains work..."
**Fix**: Run `git pull --rebase` then try push again.

Assessment Design

Formative Assessment (During Learning)

• Knowledge checks after each section
• Quick quizzes that don't feel like tests
• "Try this now" exercises with immediate feedback

Summative Assessment (After Learning)

• Realistic scenarios, not isolated facts
• Multiple correct approaches acceptable
• Clear rubric or success criteria

Self-Assessment

Provide checklists learners can use:

## Skills Checklist

After completing this tutorial, you should be able to:
- [ ] Clone a repository from GitHub
- [ ] Create and switch between branches
- [ ] Stage, commit, and push changes
- [ ] Open a pull request with description
- [ ] Respond to review comments

Accessibility Principles

Universal Design for Learning (UDL)

Principle	Application
Multiple means of representation	Text + code + diagrams
Multiple means of action	Various practice options
Multiple means of engagement	Choice, relevance, autonomy

Practical Checklist

• Alt text for all images
• Captions or transcripts for video/audio
• Clear heading hierarchy (H1 → H2 → H3)
• Adequate color contrast
• Meaningful link text (not "click here")
• Tables have proper headers
• Code examples have syntax highlighting

Quality Checklist

Before publishing instructional content:

• Clear learning objectives stated at top?
• Prerequisites explicitly listed?
• One action per numbered step?
• Worked examples before practice?
• Common errors anticipated and addressed?
• Practice opportunity with clear success criteria?
• Self-assessment checklist provided?
• Tested by someone who doesn't know the topic?

Integration with Other Skills

This skill provides the pedagogical layer for educational content:

• technical-writing-craft: Technical accuracy + instructional design = tutorials that work
• structured-communication: Content structure + learning sequence = effective curriculum
• concise-writing-craft: Brevity + chunking = manageable cognitive load
• human-voice-tone: Authentic voice + teaching = engaged learners

Quick Reference: The 7 Principles

1. Objectives First - Know what they should DO after learning
2. Sequence for Success - Simple before complex, concrete before abstract
3. Manage the Load - Chunk, scaffold, eliminate extraneous
4. Show Before Ask - Worked examples before practice
5. Predict Failure - Address errors before they happen
6. Verify Transfer - Practice that proves they can do it
7. Enable Self-Assessment - Checklists and criteria for independence

---

"The goal is not for the learner to be impressed. The goal is for the learner to be capable."