tutorial-docs

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

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