Handbook chapter template

When to use

• Shelf: learn/handbooks/<topic>/NN-chapter.mdx
• kind: handbook
• Diátaxis mode: explanation (mental models, not step-by-step ship)
• Readers served: visual learners (diagrams); perfectionists (comparison tables); agents building context before playbooks

Hub page uses handbook-hub — not this template.

Design rationale

• Explain before procedure — handbooks answer why and how pieces relate; playbooks answer do this now (Diátaxis explanation vs how-to).
• Diagram mandatory for structure sections — relationship vocabulary fails the warrant test without a visual (ZajLibrary visuals gate).
• Comparison tables for “when to use which” — parallel choices belong in tables (Google reference patterns).
• :::tip[Related] not :::next — handbooks are non-linear; link outward (handbook vs playbook spine).
• Define terms on first use — explanation docs serve beginners entering unfamiliar domains (technical writing — define terms).

Copy-paste skeleton

Use .mdx when importing diagram components.

---
title: "Chapter title"
description: One sentence — what mental model the reader leaves with.
sidebar:
  label: "Chapter title"
  order: N
category: <topic>
kind: handbook
status: current
tags: [handbook, topic]
---

<p class="eyebrow">Handbook · &lt;domain&gt;</p>

One or two sentences: **why this matters** before any detail.

## What it is

Plain-language definition. Define terms on first use.

\`\`\`mermaid
graph TD
  A["Part A"] --> B["Part B"]
\`\`\`

## How the pieces relate

&lt;Prose + table or LayerStack / PackageBoundary in .mdx&gt;

| Term | Owns | Uses |
|---|---|---|
| … | … | … |

## When to use which

| Situation | Choose | Avoid |
|---|---|---|
| … | … | … |

:::tip[Related]
[Guide](/tech-stack/laravel/codecanyon/learn/guides/) · [Playbook phase](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) · [Concept](/zajlibrary/navigation/library-shelves/resources/reference/learn-concepts/)
:::

Anti-patterns

• Do not use playbook step spine (## TL;DR, stepNumber, :::next).
• Do not ship relationship/structure sections as prose-only.
• Do not embed full deploy procedures — link to Build shelf.

Worked example

• ZajModules vs customizations
• System docs examples

Sources

• Diátaxis — Explanation — understanding-oriented handbook chapters.
• Diátaxis — Overview — handbooks vs guides vs tutorials.
• Google developer documentation style guide — Definitions — term introduction and consistency.
• Doc components — warrant test — when diagrams are mandatory.
• Writing style → Doc-type spines