# Tutorial Template

> **Use this template** for step-by-step learning guides. Longer than Getting Started, focuses on building understanding.

---

## When to Use

| Guide Type | Length | Purpose |
|------------|--------|---------|
| QUICK-START | ~1 page | Get running fast |
| GETTING-STARTED | 2-4 pages | Hands-on intro + testing |
| **TUTORIAL** | 5-15 pages | Deep learning, build something |
| REFERENCE | Variable | Lookup, not learning |

---

## Template

````markdown
# Tutorial: [Topic Name]

> **What you'll build:** [Concrete outcome in one sentence]
>
> **Time:** ~[X] minutes | **Level:** [Beginner/Intermediate/Advanced]

---

## Prerequisites

Before starting, you should:
- [ ] [Prerequisite 1]
- [ ] [Prerequisite 2]
- [ ] Completed: [Link to prior tutorial if part of series]

**Verify your setup:**
```bash
[verification command]
```

---

## What You'll Learn

By the end of this tutorial, you will:
1. [Learning objective 1 - action verb]
2. [Learning objective 2 - action verb]
3. [Learning objective 3 - action verb]

---

## Overview

[2-3 paragraph explanation of what we're building and why. Include a diagram if helpful.]

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Step 1     │ --> │  Step 2     │ --> │  Result     │
└─────────────┘     └─────────────┘     └─────────────┘
```

---

## Part 1: [First Major Section]

### Step 1.1: [Action]

[Brief explanation of what we're doing and why]

```bash
[command or code]
```

**What happened:** [Explain the result]

### Step 1.2: [Action]

[Explanation]

```bash
[command or code]
```

> **Note:** [Important callout if needed]

### Checkpoint

At this point, you should have:
- [x] [What they've accomplished]
- [x] [What they've accomplished]

**Verify:**
```bash
[verification command]
# Expected: [what they should see]
```

---

## Part 2: [Second Major Section]

### Step 2.1: [Action]

[Explanation]

```bash
[command or code]
```

### Step 2.2: [Action]

[Explanation]

```bash
[command or code]
```

> **Warning:** [Common mistake to avoid]

### Checkpoint

**Verify:**
```bash
[verification command]
```

---

## Part 3: [Third Major Section]

### Step 3.1: [Action]

[Explanation]

```bash
[command or code]
```

### Understanding [Key Concept]

[Deeper explanation of an important concept introduced in this section]

| Term | Meaning |
|------|---------|
| [Term 1] | [Definition] |
| [Term 2] | [Definition] |

### Step 3.2: [Action]

[Explanation]

```bash
[command or code]
```

### Checkpoint

**Verify:**
```bash
[verification command]
```

---

## Putting It All Together

Now let's use everything we learned:

```bash
# Complete workflow
[full example combining all parts]
```

**Result:** [What they should see/have now]

---

## Exercises

Practice what you learned with these challenges:

### Exercise 1: [Easy]
[Task description]

<details>
<summary>Hint</summary>

[Hint text]
</details>

<details>
<summary>Solution</summary>

```bash
[solution]
```
</details>

### Exercise 2: [Medium]
[Task description]

<details>
<summary>Solution</summary>

```bash
[solution]
```
</details>

### Exercise 3: [Challenge]
[Task description - combines multiple concepts]

<details>
<summary>Solution</summary>

```bash
[solution]
```
</details>

---

## Common Issues

### "[Error message]"

**Cause:** [Why this happens]

**Fix:**
```bash
[fix command]
```

### "[Another error]"

**Cause:** [Why]

**Fix:**
```bash
[fix]
```

---

## Summary

In this tutorial, you learned:

| Concept | What You Did |
|---------|--------------|
| [Concept 1] | [Brief description] |
| [Concept 2] | [Brief description] |
| [Concept 3] | [Brief description] |

**Key commands:**
```bash
[cmd1]    # [what it does]
[cmd2]    # [what it does]
[cmd3]    # [what it does]
```

---

## Next Steps

Continue your learning:

1. **[Next Tutorial]** — [What they'll learn]
2. **[Related Topic]** — [What they'll learn]
3. **[Reference Guide]** — [For deeper details]

---

## Quick Reference

```
┌─────────────────────────────────────────────────────┐
│  [TOPIC] QUICK REFERENCE                            │
├─────────────────────────────────────────────────────┤
│  [cmd1]         [description]                       │
│  [cmd2]         [description]                       │
│  [cmd3]         [description]                       │
├─────────────────────────────────────────────────────┤
│  Workflow: [step] → [step] → [step]                 │
└─────────────────────────────────────────────────────┘
```
````

---

## Structure Guidelines

### Part Organization

| Part | Content |
|------|---------|
| **Part 1** | Foundation — basic setup, first actions |
| **Part 2** | Core workflow — main topic content |
| **Part 3** | Advanced/Integration — putting it together |

### Step Structure

Each step should have:
1. **Brief intro** — What and why (1-2 sentences)
2. **Code/command** — What to do
3. **Explanation** — What happened (optional for obvious steps)

### Checkpoints

Place checkpoints:
- After each Part (major section)
- Before any destructive/irreversible action
- At natural "save points"

### Callout Types

```markdown
> **Note:** Additional helpful information

> **Warning:** Something that could cause problems

> **Tip:** Optional enhancement or shortcut
```

---

## ADHD-Friendly Tips

1. **Frequent checkpoints** — Let them verify progress
2. **No walls of text** — Break into small chunks
3. **Copy-paste code** — Don't make them type long commands
4. **Visual progress** — Use ✅ or similar for completed items
5. **Exercises optional** — Mark clearly, don't gatekeep
6. **Summary at end** — Reinforce what they learned
7. **Quick reference** — Provide a cheat sheet

---

## Checklist for New Tutorials

- [ ] Clear outcome stated at top
- [ ] Time estimate provided
- [ ] Prerequisites listed with verification
- [ ] Learning objectives are action verbs
- [ ] Each part has a checkpoint
- [ ] At least 3 exercises (easy/medium/hard)
- [ ] Common issues section
- [ ] Summary with key commands
- [ ] Next steps provided
- [ ] Quick reference at end
