back
loading skill details...
Tutorial patterns for documentation - learning-oriented guides that teach through guided doing. Use when writing a tutorial, learning guide, getting-started...
---
name: tutorial-docs
description: "Tutorial patterns for documentation - learning-oriented guides that teach through guided doing. Use when writing a tutorial, learning guide, getting-started or onboarding guide, beginner/introductory guide, or any learn-by-doing hands-on guide. Builds on the docs-style core writing principles."
user-invocable: false
---
# 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.
**Dependency:** Use this skill with `docs-style` for core writing principles. To confirm a tutorial is the right type — rather than a how-to, reference, or explanation — see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).
## 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.
```markdown
Run the development server:
```bash
npm run dev
```
You should see:
```
> Local: http://localhost:3000
> Ready in 500ms
```
Open http://localhost:3000 in your browser. You should see a welcome page with "Hello, World!" displayed.
```
### 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.
```markdown
<Warning>
Make sure you're in the project directory before running this command.
If you see "command not found", return to Step 2 to verify the installation.
</Warning>
```
### 5. Permit Repetition to Build Confidence
Repeating similar actions in slightly different contexts helps cement learning. Don't try to be efficient.
### 6. Write in the First-Person Plural
Diataxis prescribes the "we" voice for tutorials — "In this tutorial, we will build…", "Now we add…", "Let's check the output." It affirms the bond between teacher and learner: you are doing this *together*, and the teacher takes responsibility for the outcome. Reserve bare second-person imperatives ("Run this command") for the individual actions the reader performs; frame the journey itself with "we."
| Avoid | Prefer |
|-------|--------|
| "You will build a dashboard." | "In this tutorial, we'll build a dashboard." |
| "Next, configure the API." | "Now let's configure the API." |
## Tutorial Template
Use this structure for all tutorials:
```markdown
---
title: "Build your first [thing]"
description: "Learn the basics of [product] by building a working [thing]"
---
# Build Your First [Thing]
In this tutorial, we'll build a [concrete deliverable]. By the end, you'll have a working [thing] that [does something visible].
<Note>
This tutorial takes approximately [X] minutes to complete.
</Note>
## What you'll build
[Screenshot or diagram of the end result]
A [brief description of the concrete deliverable] that:
- [Visible capability 1]
- [Visible capability 2]
- [Visible capability 3]
## Prerequisites
Before starting, make sure you have:
- [Minimal requirement 1 - link to install guide if needed]
- [Minimal requirement 2]
<Tip>
New to [prerequisite]? [Link to external resource] has a quick setup guide.
</Tip>
## Step 1: [Set up your project]
[First action - always start with something that produces visible output]
```bash
[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]
```
Save the file. You should see [visible change].
<Note>
[Optional tip to prevent common mistakes]
</Note>
## Step 3: [Continue building]
[Continue with more steps, each producing visible output]
## Step 4: [Add the final piece]
[Bring it together with a final step]
You should now see [final visible result].
[Screenshot of completed project]
## What you've learned
In this tutorial, you:
- [Concrete skill 1 - what they can now do]
- [Concrete skill 2]
- [Concrete skill 3]
## Next steps
Now that you have a working [thing], you can:
- **[Tutorial 2 title]** - Continue learning by [next learning goal]
- **[How-to guide]** - Learn how to [specific task] with your [thing]
- **[Concepts page]** - Understand [concept] in more depth
```
## 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. **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:
```markdown
## Prerequisites
- A computer with macOS, Windows, or Linux
- A text editor (we recommend VS Code)
- 15 minutes of time
<Tip>
You don't need any programming experience. This tutorial explains everything as we go.
</Tip>
```
### The "You should see" Pattern
This is the most important pattern in tutorial writing. Use it constantly:
```markdown
Click **Save**. You should see a green checkmark appear next to the filename.
Run the test:
```bash
npm test
```
You should see:
```
PASS src/app.test.js
✓ renders welcome message (23ms)
Tests: 1 passed, 1 total
```
```
### Handling Errors Gracefully
Anticipate failures and guide readers back on track:
```markdown
<Warning>
If you see "Module not found", make sure you saved the file from Step 2.
Return to Step 2 and verify the import statement matches exactly.
</Warning>
```
## Components for Tutorials
### Frame Component for Screenshots
Show what success looks like:
```markdown
<Frame caption="Your completed dashboard should look like this">
</Frame>
```
### Steps Component for Procedures
For numbered sequences within a step:
```markdown
<Steps>
<Step title="Open the settings panel">
Click the gear icon in the top right corner.
</Step>
<Step title="Find the API section">
Scroll down to **Developer Settings**.
</Step>
<Step title="Generate a key">
Click **Create New Key** and copy the value shown.
</Step>
</Steps>
```
### Callouts for Guidance
```markdown
<Note>
Don't worry if the colors look different on your screen.
We'll customize the theme in the next step.
</Note>
<Warning>
Make sure to save the file before continuing.
The next step won't work without this change.
</Warning>
<Tip>
You can press Cmd+S (Mac) or Ctrl+S (Windows) to save quickly.
</Tip>
```
### Code with Highlighted Lines
Draw attention to what matters:
```markdown
```javascript {3-4}
function App() {
return (
<h1>Hello, World!</h1>
<p>Welcome to your first app.</p>
);
}
```
```
## Example Tutorial
See [references/example-weather-api.md](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
- [ ] Pre-publish gates (below) completed in order—not only self-reviewed
## Pre-publish gates
Run these **in order**. Start the next gate only after the previous **pass** is satisfied.
1. **Draft artifact** — The tutorial exists at a concrete path (file, branch, or CMS location). **Pass:** the artifact opens without guesswork.
2. **Observable outcomes** — **Pass:** every procedural step states what the reader should see next (command output, UI change, or named file)—not only what to do.
3. **Single path** — **Pass:** aside from prerequisite install links, the body does not branch into equivalent alternatives (“npm or yarn…”) unless you split into separate tutorials.
4. **Independent run** — Someone who did not write the draft follows the tutorial from a clean starting point. **Pass:** each step matches its promised outcome; any mismatch is fixed in the doc before publish (see “The Teacher Takes Responsibility” above).
## 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" |
For the full compass procedure and the other type distinctions, see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).
### 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](../docs-style/SKILL.md)**: Core writing conventions and components
- **[Diataxis compass](../docs-style/references/diataxis-compass.md)**: Type selection, the 2×2 map, and the quality model
- **[howto-docs](../howto-docs/SKILL.md)**: How-To guide patterns for task-oriented content
- **[reference-docs](../reference-docs/SKILL.md)**: Reference documentation patterns
- **[explanation-docs](../explanation-docs/SKILL.md)**: Conceptual documentation patterns
don't have the plugin yet? install it then click "run inline in claude" again.
restructured original into implexa's six-component format (intent, inputs, procedure, decision points, output contract, outcome signal) while preserving all original patterns, added edge cases (rate limits, network timeouts, auth expiry), made decision logic explicit, documented no external connections needed, and preserved author attribution.
tutorials teach beginners by having them build something real, step by step, under your guidance. the reader learns through action, not explanation. use this skill when writing any learn-by-doing content: getting-started guides, onboarding flows, beginner tutorials, or hands-on learning paths. tutorials differ from how-to guides (which solve a specific task), explanations (which build conceptual understanding), and reference docs (which describe the system). pick this when your reader wants to learn something new by making something visible and working.
no external connections or API keys required. this skill is pure content authorship.
inputs needed:
follow this workflow to write a tutorial that works:
define the concrete outcome. write one sentence: "readers will build a [specific thing] that [does something visible]." nail this first. examples: "build a weather dashboard that fetches real API data," "deploy a working chat app," "create a database schema and write three queries." not abstract ("learn about APIs") but concrete and buildable.
map the critical path. list 5-8 steps that move from nothing to working deliverable. each step must produce a visible change: a running server, a file that exists, a UI button that appears, a command that succeeds. write these as actions, not explanations. "run npm install" not "npm install is a package manager that."
write the introduction. show what they'll build (screenshot preferred). state the time commitment. list minimal prerequisites only. use this exact pattern: "Before starting, make sure you have: [item 1], [item 2]." Link to install guides for anything non-trivial. add a callout: "New to X? [Link] has a quick setup guide."
write each step in this order: (a) lead with the action as a heading: "Step 1: Set up your project" (use action verbs: set up, create, add, run, deploy). (b) give the exact instruction (what to type, what to click). (c) show the code block or command. (d) immediately after, state "You should see:" and show the exact expected output (terminal output, UI screenshot, or file content). (e) add a short confirmation: "This means [what just happened in plain language]." (f) if a common mistake exists, add a Warning callout: "If you see X, do Y."
keep each step to one visible change. if a step requires five small actions before anything appears on screen, split it. readers need feedback constantly. no step should take more than 2 minutes to complete.
eliminate all choices. do not write "you can use npm or yarn" or "optionally, add this configuration." pick one way. if there are genuinely different paths (e.g., deploy to Heroku vs AWS), create separate tutorials. one tutorial, one path.
anticipate and prevent failure. read your draft as a complete beginner. where might they get stuck? where might they mistype something? add Warning callouts before those moments. never blame the reader ("if you didn't follow step 2..."). instead: "if you see module not found, return to step 2 and verify the import statement matches exactly."
write the "what you've learned" section. list 3-5 concrete skills they now have. not "you learned about APIs" but "you can now make an HTTP GET request, parse JSON responses, and handle errors in your code."
write the "next steps" section. offer 2-4 related paths (another tutorial, a how-to guide, a concepts page). frame each as "now you can do X" not "you might want to learn Y."
run the pre-publish gates. have someone who did not write the tutorial follow it from a blank machine. if they get stuck, fix the doc before publish. this is non-optional. the tutorial failed if the reader failed.
when to write a tutorial vs another doc type:
when a step might fail:
pwd to check."when to use callouts:
<Note> for non-critical context ("don't worry if colors look different; we customize in step 5").<Warning> when the next step will fail if this one isn't done correctly.<Tip> for shortcuts or optional learning ("you can press Cmd+S to save faster").when prerequisites are too heavy:
when to offer alternatives:
# macOS / npm install then # Windows / npm install in the same block. but always show the output the same way. no branching paths.a completed tutorial markdown file (or published page) that includes, in order:
file location: place in /docs/tutorials/ or equivalent, with a descriptive slug (e.g., /docs/tutorials/build-first-weather-dashboard.md). include the markdown file, any referenced images in /docs/images/tutorials/, and any starter code in a linked GitHub repo or /docs/code-examples/.
all steps must include an observable outcome statement ("you should see:"). zero steps should describe what to do without showing what success looks like.
the reader knows the tutorial worked when:
they have a working, visible deliverable (an app running on localhost, a deployed service, a file saved with correct content). they can run it, see it, or interact with it. not abstract. not theoretical.
every step's "you should see" output matches what they see on their machine. if the output doesn't match, the tutorial failed. the reader did not fail; the tutorial did.
they completed every step without getting stuck. if they had to google something, debug on their own, or guess the next action, the tutorial is incomplete. add a callout or rewrite that step.
they can articulate what they learned. ask them: "what can you do now that you couldn't before?" if they can list 3 concrete skills from the "what you've learned" section, the tutorial worked.
they feel confident to explore further. the next-steps section should point them to 2-4 clear paths, and they should pick one without confusion.
run a pre-publish gate: have a test reader (someone who did not write the doc) follow the tutorial cold. if they succeed without questions or corrections, you're done. if they stumble anywhere, fix the doc. do not publish until this passes.
credits: original tutorial patterns authored by anderskev (clawhub). enriched and structured per Implexa quality standards.