diataxis:tutorial

What this skill does

# Tutorial writer

## Purpose

Create a true tutorial: a learning-oriented lesson in which the reader learns by doing something meaningful.

This is not a how-to guide. The aim is not to help an already-competent user complete a task, but to help a learner build skill and confidence.

## When to use

Use this skill when the user asks for:

- a beginner walkthrough
- a getting started lesson
- a first project
- onboarding material for new users

Do not use this skill for troubleshooting, advanced tasks, operational runbooks, or exhaustive product coverage.

## Tutorial promise

A tutorial should say, in effect:

"Stay with me, follow these steps, and you will successfully build or do something concrete."

The author is responsible for the learner's path and success.

## Key principles

- learning-oriented, not task-oriented
- concrete actions, not abstraction
- visible results early and often
- clear expected outcomes at each step
- minimal explanation
- no unnecessary options or alternatives
- strong reliability and testability

## Structure

Use this shape:

1. Title focused on the thing the learner will make or achieve
2. What we are going to build or do
3. Prerequisites kept minimal
4. Step-by-step lesson
5. Checkpoints with expected results
6. Short recap of what the learner now has
7. Next steps linking to how-to, reference, and explanation

## Writing rules

### Start with a concrete destination

State what the learner will accomplish, not what they will "learn".

Good:
- In this tutorial, we will build a small Kotlin client that fetches weather data.

Bad:
- In this tutorial, you will learn about networking, architecture, and design.

### Deliver visible results early

Get to a meaningful output quickly.

Every step should create an observable result:
- a command succeeds
- a UI changes
- a file appears
- a request returns data
- a test passes

### Maintain expectation

Tell the learner what should happen next.

Use language like:
- You should now see...
- The output should look like...
- If you do not see..., check...

### Minimise explanation

Only explain just enough for the step to make sense.
Move conceptual depth into explanation pages.

### Remove choices

Choose defaults for the learner.
Do not branch unless absolutely necessary.

### Favour confidence over coverage

A shorter tutorial that works is better than a broad tutorial that overwhelms.

## Inputs to gather

- exact learner starting point
- one meaningful end result
- minimal prerequisites
- stable environment assumptions
- commands, files, and outputs that can be tested
- known failure points

## Output contract

Produce a tutorial that:

- is safe for a beginner to follow
- works as written on the chosen happy path
- includes expected outputs or checkpoints
- resists distraction
- hands off naturally to deeper docs

## Anti-patterns to remove

- long conceptual detours
- option matrices
- exhaustive flags and parameters
- advice for advanced users
- hidden prerequisites
- steps without observable outcomes

## Final self-check

Before returning, verify:

- the tutorial has one achievable goal
- every step has a reason to exist
- the learner gets a result early
- the likely failure points are anticipated
- explanation is ruthlessly trimmed
- the ending points to the next appropriate docs