Guidelines for creating learning-oriented tutorial documentation. Use when writing step-by-step content that helps users learn by doing.
This skill provides guidelines for creating tutorial documentation - learning-oriented content in the Diataxis framework.
Tutorials help users learn by guiding them through a series of steps. The user follows along to gain knowledge and skills.
"I want to learn how to use this."
| Attribute | Description |
|---|---|
| Orientation | Learning |
| Focus | Study, not work |
| Goal | Help user acquire skills |
| Tone | Encouraging, supportive |
Place tutorials in: docs/getting-started/
Use this template when creating tutorial documentation:
# [Tutorial Title]
*Estimated time: [X minutes]*
## What you'll learn
By the end of this tutorial, you will:
- [Learning outcome 1]
- [Learning outcome 2]
- [Learning outcome 3]
## Prerequisites
Before starting, ensure you have:
- [Requirement 1 - e.g., Node.js 18+ installed]
- [Requirement 2 - e.g., Basic familiarity with JavaScript]
- [Requirement 3 - e.g., A code editor]
## Step 1: [Set up your environment]
[Clear instruction for what to do first]
[Command or code example]
You should see:
[Expected output]
## Step 2: [Create your first [thing]]
[Clear instruction]
[Code example]
[Brief explanation of what this does - just enough to proceed]
## Step 3: [Add [feature]]
[Clear instruction]
[Code example]
## Step 4: [Run and verify]
[Instruction to run/test what was built]
[Command]
You should see:
[Expected output showing success]
## What you've accomplished
Congratulations! You've successfully:
- [Achievement 1]
- [Achievement 2]
- [Achievement 3]
## Next steps
Now that you've completed this tutorial, you can:
- [Link to next tutorial in series]
- [Link to how-to guide for practical application]
- [Link to reference docs for deeper understanding]
---
*Having trouble? Check the [troubleshooting guide](../guides/TROUBLESHOOTING.md) or [open an issue](link-to-issues).*
Apply this checklist before finalizing any tutorial documentation.
