Tutorial Documentation Skill

This skill provides patterns for writing effective tutorials following the Diataxis framework. Tutorials are learning-oriented content where the reader learns by doing under the guidance of a teacher.

Purpose & Audience

Target readers:

• - Complete beginners with no prior experience
• Users who want to learn, not accomplish a specific task
• People who need a successful first experience with the product
• Learners who benefit from guided, hands-on practice

Tutorials are NOT:

• - How-To guides (which help accomplish specific tasks)
• Explanations (which provide understanding)
• Reference docs (which describe the system)

Core Principles (Diataxis Framework)

1. Learn by Doing, Not by Reading

Tutorials teach through action, not explanation. The reader should be doing something at every moment.

Avoid	Prefer
"REST APIs use HTTP methods to..."	"Run this command to make your first API call:"
"Authentication is important because..."

"Add your API key to authenticate:" |
| "The dashboard contains several sections..." | "Click Create Project in the dashboard." |

2. Deliver Visible Results at Every Step

After each action, tell readers exactly what they should see. This confirms success and builds confidence.

CODEBLOCK0bash
npm run dev

You should see:

Local: http://localhost:3000

Ready in 500ms

CODEBLOCK2

3. One Clear Path, Minimize Choices

Tutorials should not offer alternatives. Pick one way and guide the reader through it completely.

Avoid	Prefer
"You can use npm, yarn, or pnpm..."	"Install the dependencies:"
"There are several ways to configure..."

"Create a config file:" |
| "Optionally, you might want to..." | [Omit optional steps entirely] |

4. The Teacher Takes Responsibility

If the reader fails, the tutorial failed. Anticipate problems and prevent them. Never blame the reader.

CODEBLOCK3

5. Permit Repetition to Build Confidence

Repeating similar actions in slightly different contexts helps cement learning. Don't try to be efficient.

Tutorial Template

Use this structure for all tutorials:

CODEBLOCK4bash
[command]

You should see:

[expected output]

[Brief confirmation of what this means]

## Step 2: [Create your first thing]

[Next action with clear instruction]

code
[code to add or modify]
CODEBLOCK7

Writing Principles

Title Conventions

• - Start with action outcomes: "Build your first...", "Create a...", "Deploy your..."
• Focus on what they'll make, not what they'll learn
• Be concrete: "Build a chat application" not "Learn about real-time messaging"

Step Structure

1. 1. Lead with the action - don't explain before doing
2. Show exactly what to type or click - no ambiguity
3. Confirm success after every step - "You should see..."
4. Keep steps small - one visible change per step

Managing Prerequisites

Tutorials are for beginners, so minimize prerequisites:

CODEBLOCK8

The "You should see" Pattern

This is the most important pattern in tutorial writing. Use it constantly:

CODEBLOCK9bash
npm test

You should see:

PASS src/app.test.js
✓ renders welcome message (23ms)

Tests: 1 passed, 1 total
CODEBLOCK11

Handling Errors Gracefully

Anticipate failures and guide readers back on track:

CODEBLOCK12

Components for Tutorials

Frame Component for Screenshots

Show what success looks like:

CODEBLOCK13

Steps Component for Procedures

For numbered sequences within a step:

CODEBLOCK14

Callouts for Guidance

CODEBLOCK15

Code with Highlighted Lines

Draw attention to what matters:

CODEBLOCK16javascript {3-4}
function App() {
return (

Hello, World!

Welcome to your first app.

);
}
CODEBLOCK17

Example Tutorial

See references/example-weather-api.md for a complete example tutorial demonstrating all principles above. The example builds a weather dashboard that fetches real API data.

Checklist for Tutorials

Before publishing, verify:

• - [ ] Title describes what they'll build, not what they'll learn
• [ ] Introduction shows the concrete end result
• [ ] Prerequisites are minimal (beginners don't have much)
• [ ] Every step produces visible output
• [ ] "You should see" appears after each significant action
• [ ] No choices offered - one clear path only
• [ ] No explanations of why things work (save for docs)
• [ ] Potential failures are anticipated with recovery guidance
• [ ] "What you've learned" summarizes concrete skills gained
• [ ] Next steps guide to continued learning
• [ ] Tutorial tested end-to-end by someone unfamiliar with it

When to Use Tutorial vs Other Doc Types

User's mindset	Doc type	Example
"I want to learn"	Tutorial	"Build your first chatbot"
"I want to do X"

How-To | "How to configure SSO" | | "I want to understand" | Explanation | "How our caching works" | | "I need to look up Y" | Reference | "API endpoint reference" |

Tutorial vs How-To: Key Differences

Aspect	Tutorial	How-To
Purpose	Learning through doing	Accomplishing a specific task
Audience

Complete beginners | Users with some experience | | Structure | Linear journey with one path | Steps to achieve a goal | | Choices | None - one prescribed way | May show alternatives | | Explanations | Minimal - action over theory | Minimal - focus on steps | | Success | Reader learns and gains confidence | Reader completes their task | | Length | Longer, more hand-holding | Shorter, more direct |

Related Skills

• - docs-style: Core writing conventions and components
• howto-docs: How-To guide patterns for task-oriented content
• reference-docs: Reference documentation patterns
• explanation-docs: Conceptual documentation patterns