---
type: tutorial
divio_category: learning-oriented
target_audience: beginners
purpose: hands-on-lesson
outcome: learner-can-do-something
---

# Tutorial: {TUTORIAL_TITLE}

> **Divio Type**: Tutorial (Learning-Oriented)
> **Target Audience**: Beginners with little to no prior experience
> **Purpose**: Guide learners through completing a meaningful task step-by-step
> **Outcome**: By the end, learners will have accomplished something concrete

## What You'll Learn

In this tutorial, you will:
- {Bullet point: First thing they'll accomplish}
- {Bullet point: Second thing they'll accomplish}
- {Bullet point: Third thing they'll accomplish}

**Time to Complete**: Approximately {X} minutes

## Before You Begin

**Prerequisites**:
- {Required knowledge or skill - keep minimal for beginners}
- {Required tool or software with installation link}
- {Required account or access}

**What You'll Need**:
- {Physical or digital resources needed}
- {Optional: Link to starter code or files}

## Step 1: {First Step Title}

{Brief introduction to what this step accomplishes}

**Do this**:

```bash
# Exact command to run
{command-here}
```

**You should see**:

```
{Expected output}
```

✅ **Checkpoint**: {How learner knows this step succeeded}

> **💡 Learning Note**: {Brief explanation of what just happened - keep it short}

## Step 2: {Second Step Title}

{Brief introduction to what this step builds on the previous one}

**Do this**:

```{language}
# Code to write or run
{code-here}
```

**Where to put it**: {Exact file location}

✅ **Checkpoint**: {How learner knows this step succeeded}

> **💡 Learning Note**: {Brief explanation}

## Step 3: {Third Step Title}

{Continue pattern - each step builds on the last}

**Do this**:

{Concrete action}

✅ **Checkpoint**: {Verification}

## Step 4: {Continue as needed...}

{Maintain momentum - learners should see progress at every step}

## What You've Accomplished

Congratulations! You've completed {the task}. You now have:
- ✅ {Concrete accomplishment #1}
- ✅ {Concrete accomplishment #2}
- ✅ {Concrete accomplishment #3}

## Next Steps

Now that you've learned {the basics}, you can:
- **Learn More**: See [Explanation: {Topic}](../explanation/{link}) to understand why this works
- **Solve Problems**: Check [How-To: {Task}](../how-to/{link}) for specific scenarios
- **Reference**: Refer to [{API/CLI}](../reference/{link}) for all options

## Troubleshooting

**Problem**: {Common issue learners face}
**Solution**: {Exact steps to fix it}

**Problem**: {Another common issue}
**Solution**: {Exact steps to fix it}

---

## Write the Docs Best Practices (Remove this section before publishing)

**Tutorial Principles**:
- ✅ Learning-oriented: Help learners gain competence
- ✅ Allow learner to learn by doing
- ✅ Get learners started quickly with early success
- ✅ Make sure tutorial works reliably
- ✅ Give immediate sense of achievement at each step
- ✅ Ensure learner sees results immediately
- ✅ Make tutorial repeatable and reliable
- ✅ Focus on concrete steps, not abstract concepts
- ✅ Provide minimum necessary explanation (link to Explanation docs)
- ✅ Ignore options and alternatives (focus on the happy path)

**Accessibility**:
- ✅ Use proper heading hierarchy (H1 → H2 → H3, no skipping)
- ✅ Provide alt text for all images and screenshots
- ✅ Use clear, plain language (avoid jargon, or define it immediately)
- ✅ Code blocks have language tags for syntax highlighting
- ✅ Use descriptive link text (not "click here")

**Inclusivity**:
- ✅ Use diverse names in examples (not just "John", "Alice")
- ✅ Gender-neutral language where possible
- ✅ Avoid cultural assumptions (not everyone celebrates the same holidays)
- ✅ Consider accessibility needs (keyboard navigation, screen readers)

**Tutorial-Specific Guidelines**:
- Start with a working example, not theory
- Each step should produce a visible result
- Don't explain everything - just enough to complete the task
- Link to Explanation docs for deeper understanding
- Test the tutorial with a beginner (does it work as written?)
- Keep it short - 15-30 minutes maximum
- Use consistent formatting for commands, code, and checkpoints
