BMAD-METHOD/expansion-packs/bmad-technical-writing/tasks/develop-tutorial.md

<!-- Powered by BMAD™ Core -->

# Develop Tutorial

---

task:
  id: develop-tutorial
  name: Develop Tutorial
  description: Create hands-on step-by-step tutorial with tested code, clear instructions, and troubleshooting
  persona_default: tutorial-architect
  inputs:
    - tutorial-topic
    - learning-objective
    - difficulty-level
  steps:
    - Identify specific learning objective for tutorial
    - Define prerequisite knowledge and setup requirements
    - Design step-by-step progression (8-15 steps typical)
    - Write clear, actionable instructions for each step
    - Create and test code examples for each step
    - Document expected outputs at each step
    - Add troubleshooting section for common issues
    - Test complete tutorial end-to-end
    - Verify progressive difficulty and skill building
    - Include summary and next steps
    - Run execute-checklist.md with tutorial-effectiveness-checklist.md
    - Use template tutorial-section-tmpl.yaml with create-doc.md
  output: tutorials/{{tutorial-slug}}.md

---

## Purpose

Create effective hands-on tutorials that guide learners through building something concrete while learning key concepts. Great tutorials balance clear instruction with learning depth.

## Prerequisites

- Learning objective clearly defined
- Subject matter expertise in tutorial topic
- Testing environment available
- Access to learning-frameworks.md knowledge base

## Workflow Steps

### 1. Identify Learning Objective

Define what students will accomplish:

**Specific and Measurable:**
- "Build a REST API with authentication" (good)
- "Learn about APIs" (too vague)

**Achievable Scope:**
- 30-45 minutes for basic tutorials
- 1-2 hours for intermediate
- 2-4 hours for advanced

**Clear Success Criteria:**
- What will work at the end?
- What skills will be demonstrated?
- What can student verify?

### 2. Define Prerequisites

Be explicit about requirements:

**Knowledge Prerequisites:**
- "Understanding of Python functions and classes"
- "Completed Tutorial 2: Flask Basics"
- "Familiarity with HTTP request/response cycle"

**Software Requirements:**
- "Python 3.11+"
- "PostgreSQL 15+ running locally"
- "VS Code or similar editor"

**Setup Steps:**
- "Clone starter repository"
- "Create virtual environment"
- "Install dependencies: `pip install -r requirements.txt`"

**Time Estimates:**
- Setup time: 10 minutes
- Tutorial time: 45 minutes
- Total: ~1 hour

### 3. Design Step-by-Step Progression

Plan the tutorial flow (typically 8-15 steps):

**Logical Progression:**
1. Setup and initialization
2. Core concept introduction
3. Basic implementation
4. Build on basics
5. Add complexity
6. Handle edge cases
7. Test/validate
8. Summary/reflection

**Each Step Should:**
- Build on previous steps
- Accomplish one clear goal
- Be testable/verifiable
- Take 3-8 minutes

**Progressive Difficulty:**
- Start simple (foundational)
- Add complexity gradually
- End with realistic scenario

### 4. Write Clear Instructions

Use consistent, actionable format:

**Step Format:**
```
**Step N: [Action-Oriented Title]**

[Brief explanation of what this step accomplishes]

**Instructions:**
1. [Specific action in imperative voice]
2. [Next action]
3. [Etc.]

**Code:**
```language
[Complete code to add/modify]
```

**Expected Output:**
```
[What student should see]
```

**Why This Matters:**
[Explain the concept or purpose]

**Verification:**
[How to confirm this step worked]
```

**Imperative Voice:**
- "Create a new file..." (good)
- "You should create..." (wordy)
- "We'll create..." (okay but less direct)

### 5. Create and Test Code Examples

Develop working code for every step:

**Code Quality:**
- Must run exactly as shown
- Include all necessary imports
- Show complete context
- Follow best practices
- Include comments explaining key lines

**Testing:**
- Run every code example
- Verify outputs match documentation
- Test in fresh environment
- Check for missing dependencies
- Validate error messages

**Incremental Development:**
- Each step adds to previous code
- Show only what changes (or full file if clearer)
- Maintain working state after each step
- Avoid breaking changes mid-tutorial

**Use:** create-code-example.md and test-code-examples.md tasks

### 6. Document Expected Outputs

Show what success looks like:

**After Key Steps:**
```
After Step 3, running `python app.py` should display:
 * Running on http://127.0.0.1:5000
 * Debug mode: on

Visiting http://localhost:5000/health should return:
{"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"}
```

**Screenshots (where helpful):**
- UI results
- Browser developer tools
- Database state
- Terminal output

**File Structure:**
```
After Step 5, your project should look like:
tutorial-app/
├── app.py
├── models/
│   └── user.py
├── routes/
│   └── auth.py
└── tests/
    └── test_auth.py
```

### 7. Add Troubleshooting Section

Anticipate and solve common problems:

**For Each Common Issue:**

**Problem:** [Error message or symptom]

**Likely Cause:** [What usually causes this]

**Diagnosis:** [How to check for this issue]

**Fix:** [Step-by-step solution]

**Verification:** [How to confirm it's fixed]

**Example:**
```
**Problem:** ImportError: No module named 'flask'

**Cause:** Flask not installed or wrong Python environment

**Diagnosis:**
1. Check virtual environment activated: `which python`
2. Check installed packages: `pip list | grep -i flask`

**Fix:**
1. Activate virtual environment: `source venv/bin/activate`
2. Install Flask: `pip install flask`
3. Verify: `python -c "import flask; print(flask.__version__)"`

**Verification:** Re-run your app - should start without import errors
```

**Include 3-5 most common issues** based on typical student mistakes.

### 8. Test Tutorial End-to-End

Validate the complete tutorial:

**Fresh Environment Test:**
- Start with clean environment
- Follow your own instructions exactly
- Don't skip any steps
- Note any assumptions you made
- Time how long it actually takes

**Someone Else Tests:**
- Have another person try the tutorial
- Watch for confusion points
- Note questions they ask
- Identify unclear instructions

**Validation Questions:**
- Does every step work as described?
- Are outputs accurate?
- Is prerequisite list complete?
- Is difficulty appropriate?
- Does learning objective get achieved?

**Use:** tutorial-effectiveness-checklist.md

### 9. Verify Progressive Difficulty

Ensure appropriate skill building:

**Check Progression:**
- Early steps are simple and foundational
- Complexity increases gradually
- No sudden jumps in difficulty
- Builds on prior knowledge systematically

**Cognitive Load:**
- Not too much new information at once
- One new concept per step when possible
- Reinforcement through repetition
- Clear explanations for complex topics

**Scaffolding:**
- More guidance early
- Gradually reduce hand-holding
- Final steps require more independence
- Prepares for next-level tutorials

### 10. Include Summary and Next Steps

Conclude effectively:

**What You Learned:**
- Recap key concepts covered
- Skills practiced in tutorial
- How this connects to broader topic

**What You Built:**
- Concrete deliverable description
- How it demonstrates learning
- Real-world applications

**Next Steps:**
- Related tutorials to try
- How to extend this project
- Resources for deeper learning

**Extension Challenges (Optional):**
- "Add password reset functionality"
- "Implement email verification"
- "Add OAuth2 social login"

## Output

Complete tutorial should include:

- Clear learning objective
- Explicit prerequisites
- 8-15 step-by-step instructions
- Tested, working code
- Expected outputs
- Troubleshooting guide
- Summary and next steps

**Use template:** tutorial-section-tmpl.yaml

## Quality Standards

Effective tutorial:

✓ Clear, specific learning objective
✓ Complete prerequisite list
✓ Actionable, numbered steps
✓ All code tested and works
✓ Expected outputs documented
✓ Troubleshooting for common issues
✓ Progressive difficulty
✓ Achievable in stated time
✓ Engaging and motivating

## Common Pitfalls

Avoid:

❌ Skipping setup steps (assumes too much)
❌ Code that doesn't actually run
❌ Unclear or vague instructions
❌ Jumping difficulty too quickly
❌ No verification steps
❌ Missing expected outputs
❌ Untested tutorial (always test!)
❌ Too long (break into multiple tutorials)

## Next Steps

After creating tutorial:

1. Include in relevant chapter
2. Add to tutorial repository
3. Test with target audience if possible
4. Gather feedback and iterate
5. Update based on common student questions