Tutorial Writer Skill

Purpose

Create comprehensive, beginner-friendly tutorials that take learners from zero to a working result. Follows the Diátaxis Tutorial pattern for learning-oriented documentation. Verifies all APIs against source code before documenting, with complete working examples that have been tested.

When to Load Additional References

The workflow below covers the essential tutorial creation process. Load detailed references when:

For complete tutorial structure and examples:

Read `~/.claude/skills/tutorial-writer/references/TUTORIAL-TEMPLATE.md`

Use when: Creating a new tutorial, need complete markdown template, step structure examples, metadata format

For avoiding common mistakes:

Read `~/.claude/skills/tutorial-writer/references/PITFALLS-GUIDE.md`

Use when: Reviewing tutorial quality, 7 common pitfalls with BAD/GOOD examples, recovery strategies

For testing and verification procedures:

Read `~/.claude/skills/tutorial-writer/references/TESTING-VERIFICATION.md`

Use when: Need to test tutorial, create test environment, verify APIs, check time estimates, beginner testing protocol

For detailed Diátaxis framework guidance:

Read `~/.claude/skills/shared/references/DIATAXIS-FRAMEWORK.md`

Use when: Understanding Diátaxis tutorial pattern, comparing with other doc types (how-to, explanation, reference)

Diátaxis Framework: Tutorial

Tutorial Type Characteristics:

• Learning-oriented - Teaching, not just documenting
• Beginner-focused - Takes learner from zero to working result
• Step-by-step - Explicit, numbered steps with clear progression
• Success criteria - Learner can verify each step worked
• Minimal explanations - WHAT to do, not WHY it works (link to explanations)
• Safe environment - No production concerns, focus on learning
• Confidence building - Early steps are very simple to build momentum
• Complete examples - Everything needed to succeed included

What NOT to Include:

• ❌ Complete API reference - Link to api-doc-writer docs
• ❌ Problem-solving patterns - That's migration-guide-writer territory
• ❌ Deep explanations of WHY - Link to explanation docs
• ❌ Production deployment - Keep focus on learning basics

Critical Rules (Zero Tolerance)

P0 - CRITICAL Violations (Must Fix)

1. Fabricated APIs - Methods that don't exist in source code
2. Wrong Signatures - Incorrect parameter types or names
3. Invalid Code - Examples that won't compile or run
4. Missing Success Criteria - Steps without verification method
5. Untested Examples - Code you haven't actually run

P1 - HIGH Violations (Should Fix)

6. Too Advanced - Assumes knowledge beginner doesn't have
7. No Prerequisites - Doesn't state what's needed before starting
8. Missing Expected Output - Doesn't show what success looks like
9. No Time Estimates - Learner doesn't know how long it takes

P2 - MEDIUM Violations

10. Too Much Explanation - Getting into WHY when should focus on WHAT
11. Marketing Language - Buzzwords instead of clear instructions

Workflow Overview

Step 1: Goal Definition (5-10 minutes)

Define the learning outcome:

• What they'll learn: Specific skill or capability
• Target audience: Experience level, prerequisites
• Success criteria: By the end, learner will be able to...
• What they'll build: Concrete deliverable (not abstract understanding)

Step 2: Source Code Research (10-15 minutes)

CRITICAL: Verify all APIs before writing.

# Read source files for APIs
Read [source_files_for_apis]

# Extract exact signatures
# Verify imports
# Find or create working example
# Check test files for usage patterns

Create API verification checklist:

## APIs to Use in Tutorial

- [ ] `APIMethod1` - Verified in [source_file.ext:line]
- [ ] `APIMethod2` - Verified in [source_file.ext:line]
- [ ] `ConfigOption1` - Verified in [config_file.ext]

All signatures copied exactly ✅
All imports verified ✅

Test the example yourself - This is REQUIRED, don't guess!

Step 3: Step Breakdown (10-15 minutes)

Break working example into logical steps:

Principles:

1. Start absurdly simple - First step should be trivial (builds confidence)
2. One concept per step - Don't introduce multiple new things at once
3. Clear success criteria - Each step has verifiable outcome
4. Realistic time estimates - Be honest about time needed
5. Progressive complexity - Each step slightly harder than previous

For complete step breakdown examples: See references/TUTORIAL-TEMPLATE.md

Step 4: Writing (20-30 minutes)

Tutorial structure:

# Getting Started with [System/Feature]

[Brief introduction - 2-3 sentences]

## Prerequisites

**Before you start, you need:**

- [Requirements with version numbers]

**Check your setup:** [commands to verify]

## What You'll Build

- ✅ [Concrete outcome 1]
- ✅ [Concrete outcome 2]

**Total time**: [Realistic estimate]

---

## Step 1: [Action] ([time] minutes)

[Very brief context - 1-2 sentences max]

[Code with VERIFIED APIs]

**Run it:** [command]

**Expected output:** [EXACT output from testing]

✅ **Success check**: [Verification]

---

[Continue with remaining steps...]

## Complete Working Code

[Full, tested code]

## What You Learned

- ✅ [Skill 1]
- ✅ [Skill 2]

## Next Steps

- **Explore more**: [API Reference link]
- **Solve problems**: [How-To Guides link]

For complete template with all sections: See references/TUTORIAL-TEMPLATE.md

Step 5: Testing (15-20 minutes)

CRITICAL: Actually run through the tutorial yourself.

This is NOT optional. You MUST test the tutorial.

# Create fresh environment
# Follow your own tutorial exactly
# Do NOT skip any steps
# Do NOT assume things work

As you test, verify:

• Each command produces stated output
• Success criteria are achievable
• Time estimates are realistic (add 50% buffer for beginners)
• No steps are confusing or ambiguous
• Prerequisites are sufficient
• Complete code at end works
• All APIs work as shown

If ANY step fails during testing:

• ❌ Do NOT publish tutorial
• Fix the step
• Test again from beginning
• Only publish after complete successful run-through

For detailed testing procedures: See references/TESTING-VERIFICATION.md

Step 6: Verification (5-10 minutes)

Verification checklist:

## Tutorial Verification Checklist

### Testing (P0 - CRITICAL)

- [ ] Tutorial tested start-to-finish
- [ ] All commands run successfully
- [ ] All outputs match documentation
- [ ] Complete code tested and works

### API Verification (P0 - CRITICAL)

- [ ] All APIs verified against source
- [ ] All signatures exact
- [ ] All imports real
- [ ] No fabricated methods

### Learning Structure (P1 - HIGH)

- [ ] Success criteria for each step
- [ ] Time estimates for each step
- [ ] Prerequisites clearly stated
- [ ] Expected outputs documented

Add metadata footer to tutorial:

---

**Tutorial Metadata**

**Last Updated**: [YYYY-MM-DD]
**System Version**: [Version this tutorial is for]
**Verified**: ✅ Tutorial tested and working
**Test Date**: [YYYY-MM-DD]

**Verification**:

- ✅ All code examples tested
- ✅ All APIs verified against source
- ✅ Expected outputs confirmed

**Source files verified**:

- `path/to/source/file1.ext`

Common Pitfalls to Avoid

1. Assuming Too Much Knowledge - Start from absolute zero
2. Missing Expected Output - Show exact output for every command
3. No Success Verification - Every step needs verification method
4. Too Many Concepts Per Step - One new concept at a time
5. Fabricated or Untested Code - All code must be tested
6. Too Much Explanation - Focus on WHAT, link to WHY
7. Unrealistic Time Estimates - Test with beginners, include buffer

For detailed pitfall examples with BAD/GOOD comparisons: See references/PITFALLS-GUIDE.md

Integration with Other Skills

Works With:

• api-doc-writer - Link to API reference for deeper info
• migration-guide-writer - After tutorial, guide to migrate existing code
• api-documentation-verify - Verify tutorial code accuracy

Invokes:

• None (standalone skill)

Invoked By:

• User (manual invocation)
• When onboarding documentation needed
• After major feature releases

Output Format

Primary Output: Markdown file with structured tutorial

File Location:

• docs/tutorials/getting-started-with-[feature].md
• TUTORIAL.md in project root
• docs/getting-started/[feature].md

Time Estimates

Simple Tutorial (< 5 steps, single concept): 1-2 hours to create Medium Tutorial (5-10 steps, multiple concepts): 2-4 hours to create Complex Tutorial (10+ steps, advanced concepts): 4-8 hours to create

Include testing time! Testing often takes as long as writing.

Success Criteria

Tutorial is complete when:

• ✅ Tested start-to-finish successfully
• ✅ All APIs verified against source code
• ✅ All code examples work
• ✅ All commands produce documented output
• ✅ Success criteria clear for each step
• ✅ Time estimates realistic for beginners
• ✅ Prerequisites clearly stated
• ✅ Progressive complexity (simple → complex)
• ✅ Complete working code at end
• ✅ No fabricated APIs
• ✅ No marketing language
• ✅ Minimal explanations (WHAT not WHY)

Special Considerations

Emoji Usage (Exception to No-Emoji Rule)

Tutorials ARE allowed to use structural emojis for clarity:

✅ Allowed (structural/functional):

• ✅ Success checkmarks for verification
• ❌ Error indicators
• ⚠️ Warning symbols

❌ Not Allowed (decorative/marketing):

• 🚀 "Blazing fast"
• 💯 "Perfect"
• 🎉 "Exciting"

Language Style

Use clear, direct language:

• "Create a file" not "Let's create a file"
• "Run the command" not "Now we'll run the command"
• "Install the package" not "You need to install the package"

Be encouraging but factual:

• ✅ "You've successfully created your first task"
• ❌ "Amazing! You're doing great!"

Beginner-Friendly Practices

1. No jargon without explanation
2. Link to prerequisite concepts
3. Show exact commands, not descriptions
4. Include complete context (imports, setup)
5. Verify each step immediately
6. Build confidence with early wins
7. Keep explanations minimal
8. Link to deeper explanations

Example Usage

# Manual invocation
/skill tutorial-writer

# User request
User: "I need a getting started guide for new developers"
Assistant: "I'll use tutorial-writer to create a beginner-friendly tutorial"

# After testing
User: "Create a tutorial for the TaskService API"
Assistant: "I'll create a step-by-step tutorial, test it, and verify all APIs"

References

• Diátaxis Framework: https://diataxis.fr/tutorials/
• Tutorial Template: references/TUTORIAL-TEMPLATE.md
• Pitfalls Guide: references/PITFALLS-GUIDE.md
• Testing & Verification: references/TESTING-VERIFICATION.md
• Diátaxis Details: ~/.claude/skills/shared/references/DIATAXIS-FRAMEWORK.md

Related Agent

For comprehensive documentation guidance that coordinates this and other documentation skills, use the documentation-coordinator agent.