/tutorial-docs

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.

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:

---
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 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