Guide template

When to use

• Shelf: learn/guides/<topic>/
• kind: guide
• Diátaxis mode: tutorial (focused learning unit — study, not ship-whole-workflow)
• Readers served: learners building understanding; agents needing conceptual map before playbooks

Design rationale

• What you’ll learn upfront — tutorials state learning outcomes before content (Diátaxis tutorials).
• Before you start gates — prerequisites prevent frustration mid-guide (Google intro patterns).
• Numbered ## sections, not <Steps> for long prose — section-level teaching uses headings; reserve <Steps> for tight procedures (writing-style formatting toolkit).
• Summary closes the mental model — three bullets max for retention (learning design — recap).
• Diagram when section maps process or structure — warrant test applies per section (visuals gate).

Copy-paste skeleton

---
title: "Guide title"
description: One sentence — what the reader will understand after reading.
sidebar:
  label: "Guide title"
  order: N
category: <topic>
kind: guide
status: current
tags: [guide, topic]
---

<p class="eyebrow">Guide · &lt;topic&gt;</p>

## What you'll learn

- &lt;Outcome 1&gt;
- &lt;Outcome 2&gt;

## Before you start

- **Prerequisites:** &lt;links or one-line reqs&gt;
- **Time:** ~&lt;N&gt; min read

## 1. &lt;First major idea&gt;

Short paragraph. If this section maps a **relationship or process**, add a Mermaid block or diagram component.

## 2. &lt;Second major idea&gt;

…

## Summary

Three bullets max — the mental model in plain language.

:::tip[Go deeper]
[Handbook chapter](/tech-stack/laravel/codecanyon/learn/handbooks/) · [Playbook when ready to execute](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/)
:::

Anti-patterns

• Do not use full playbook step spine on guides unless the page is truly one executable step.
• Do not ship process/relationship sections without diagrams.
• Do not duplicate entire playbooks — link to Build when ready to execute.

Worked example

• Build an MCP server
• System docs examples

Sources

• Diátaxis — Tutorials — learning-oriented guides with outcomes.
• Diátaxis — Overview — guides vs handbooks vs how-to playbooks.
• Google developer documentation style guide — Introductions — scope and prerequisites.
• NN/g — How users read on the web — scannable sections and summaries.
• Writing style → Doc-type spines