How-To / Tutorial Guide Template

Back to Markdown Style Guide — Read the style guide first for formatting, citation, and emoji rules.

Use this template for: Step-by-step tutorials, how-to guides, onboarding walkthroughs, runbooks, setup instructions, or any document whose primary job is teaching someone to do something. Designed so the reader succeeds on the first attempt.

Key features: Prerequisites with verification commands, numbered steps with expected output at each stage, "verify it works" checkpoints, troubleshooting section for common failures, and "what's next" pathways.

Philosophy: A how-to guide fails if the reader gets stuck. Every step should be verifiable — the reader should be able to confirm they did it right before moving to the next one. Anticipate the exact moment they'll wonder "did that work?" and put a checkpoint there. Include the error messages they'll actually see, not just the happy path.

How to Use

Copy this file to your project
Replace all [bracketed placeholders] with your content
Test the guide yourself from scratch — follow every step on a clean machine. If you skip this, the guide has bugs.
Add Mermaid diagrams for process overviews, decision points, or architecture context
Include actual output (trimmed) at every verification step — don't just say "you should see output"

The Template

Everything below the line is the template. Copy from here:

[How to: Specific Task Description]

[Estimated time: N minutes] · [Difficulty: Beginner / Intermediate / Advanced] · [Last verified: Date]

📋 Overview

What you'll accomplish

[One paragraph: what the reader will have built, configured, or achieved by the end of this guide. Be concrete.]

What you'll learn

[Skill or concept 1]
[Skill or concept 2]
[Skill or concept 3]

Process overview

mermaid

flowchart LR
    accTitle: Tutorial Process Overview
    accDescr: High-level steps from prerequisites through setup, configuration, and verification

    prereqs([📋 Prerequisites]) --> setup[🔧 Setup]
    setup --> configure[⚙️ Configure]
    configure --> build[📦 Build]
    build --> verify[✅ Verify]

    classDef done fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    class verify done

📋 Prerequisites

Before starting, ensure you have:

Requirement	Version	Verify with	Install link
[Tool/Runtime]	≥ [version]	`[command] --version`	Install guide
[Dependency]	≥ [version]	`[command] --version`	Install guide
[Account/Access]	—	[How to verify]	Sign up

Verify all prerequisites:

bash

# Run each command — all should succeed before proceeding
[command1] --version    # Expected: [version] or higher
[command2] --version    # Expected: [version] or higher

⚠️ Don't skip this. Step 3 will fail if [specific prerequisite] isn't installed correctly.

🔧 Steps

Step 1: [Action verb — Set up / Create / Configure / Install]

[Brief context: why this step is necessary — one sentence.]

bash

[command to run]

Expected output:

[What the terminal should show — include actual output, trimmed if long]

💡 Tip: [Helpful context about this step — common variation, what to do if on a different OS, etc.]

Step 2: [Action verb]

[Brief context.]

bash

[command to run]

Expected output:

[What you should see]

If you see an error here, check:

[Most common cause and fix]
[Second most common cause and fix]

Step 3: [Action verb]

[Brief context.]

[If this step involves editing a file, show the exact content:]

yaml

# config/[filename]
[key]: [value]
[key]: [value]

# [Comment explaining what this section does]
[key]:
  [nested_key]: [value]
  [nested_key]: [value]

📌 Important: [Critical detail about this configuration — what breaks if you get it wrong]

Step 4: [Action verb]

[Brief context.]

bash

[command to run]

Expected output:

[What you should see]

Step 5: [Action verb — this should be the final action]

[Brief context.]

bash

[final command]

✅ Verify it works

Run through these checks to confirm everything is working:

Check	Command	Expected result
[Check 1]	`[command]`	[What success looks like]
[Check 2]	`[command]`	[What success looks like]
[Check 3]	`[command]`	[What success looks like]

All checks pass? You're done. Jump to What's next.

Something failed? See Troubleshooting below.

🔧 Troubleshooting

"[Exact error message the reader will see]"

Cause: [What triggers this error — be specific]

Fix:

bash

[exact commands to resolve]

Verify the fix:

bash

[command to confirm the error is resolved]

"[Another common error message]"

Cause: [What triggers this]

Fix:

[Step 1]
[Step 2]
Re-run the step that failed

"[Third common issue — might not be an error message but a symptom]"

Cause: [What causes this behavior]

Fix:

[Solution with commands]

Still stuck?

Search existing issues: docs/project/issues/
Ask for help: docs/project/kanban/
File a bug: issue template

🚀 What's next

Now that you've completed this guide:

[Next tutorial] — What it covers and why you'd want to do it next
[Reference docs] — Where to learn the full feature set
[Advanced topic] — Deeper dive for when you're ready

<details> <summary><strong>📋 Quick reference card</strong></summary>

Key commands and values from this guide for future reference:

Action	Command
[Start]	`[command]`
[Stop]	`[command]`
[Check status]	`[command]`
[View logs]	`[command]`
[Reset]	`[command]`

</details>

🔗 References

Official documentation — [Which section is most relevant]
Source repository — [For bug reports and contributions]

Last verified: [Date] on [OS/Platform version] · Maintained by [Team/Author]