Tutorial Template

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/templates/tutorial.md
Description	Not specified

Source Content

Tutorial Template

Learning by doing. The reader is new and finishes with something built and working. Diátaxis mode: tutorial — teach one path, defer options and edge cases to the reference.

Skeleton

# Build {{a concrete thing}} with {{tool}}

{{Two-person story first — it sets the tone before anything else is said:
"Jack skipped the setup check and lost an hour to a missing env var. Jill
ran the check first and was building in five minutes. This tutorial
follows Jill's path."}}

{{What you'll build — one sentence, ideally a picture of the end result.}}
{{What you'll learn; prerequisites; time to complete.}}

{{Mermaid flowchart of the steps ahead — follow the diagram rules in ../mermaid.md.}}
_{{What to notice in the diagram.}}_

## {{First tangible result}}

{{Why this step matters, the commands or code, and how to verify it worked.}}

## {{Build on the previous step}}

{{Connect to what came before; introduce one new concept; hands-on.}}

## Where to go next

{{Variations to try; related topics; the reference page for depth.}}

## The useful ending

{{One or two sentences, after everything above: what each person from the
opening walked away with, now that this is written down.}}

Rules for this template

• Every step ends with a verification: “you should see…”.
• One path only — no forks, no “alternatively”. Options belong in the reference.
• Config values go one per line in a list or code block, never chained in prose.
• Run scripts/readability.py before shipping; tutorials especially must stay at an 8th-grade level.
• Cast: always Jack (the path with friction) and Jill (the path that works) — see ../personas.md.
• Reminders: story, own line per person · useful ending.
• Format: short paragraphs · lists and tables · diagram + “what to notice”.