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

1. Copy this file to your project
2. Replace all [bracketed placeholders] with your content
3. Test the guide yourself from scratch — follow every step on a clean machine. If you skip this, the guide has bugs.
4. Add Mermaid diagrams for process overviews, decision points, or architecture context
5. 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

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:

Verify all prerequisites:

# 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.]

[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.]

[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:]

# 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.]

[command to run]

Expected output:

[What you should see]

---

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

[Brief context.]

[final command]

---

✅ Verify it works

Run through these checks to confirm everything is working:

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:

[exact commands to resolve]

Verify the fix:

[command to confirm the error is resolved]

---

"[Another common error message]"

Cause: [What triggers this]

Fix:

1. [Step 1]
2. [Step 2]
3. 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:

</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]