explain

name	explain
description	Conventions for writing a Markdown explainer that walks the reader through a concept or system. Lays out term-list formatting, Mermaid diagram rules, granularity expectations, and a fixed five-part structure. Use when the user asks for an explainer, a concept write-up, a glossary section, or otherwise wants a system or idea documented for another reader.

Explainer Document Conventions

Term handling

• Put a term list at the top of the document in table form (| Term | Description |). Every specialised term used in the body must be defined in this list at first occurrence.
• A term-list entry defines what the term is in one or two sentences. The functional or behavioural detail goes in the body, not in the term list.
• Even widely recognised proper nouns (industry-standard product names, infrastructure components, etc.) get defined here. Assume the reader does not know them.
• When defining a compound term, define the constituent words too. If the compound has three words, give all three their own entries — readers cannot be expected to infer one from another.

Diagram conventions

• Use Mermaid for diagrams. Do not use ASCII art.
• Every node label is a term that exists in the term list. Do not introduce a new term inside a diagram.
• Do not put <br/> inside a Mermaid node. Many renderers display the literal HTML tag. If a line break is needed, separate with / or shorten the text to fit one line.
• For diagrams with four or more nodes, or where any label is long, use graph TD (top-down). graph LR (left-right) collapses long-label graphs into an unreadable horizontal strip.

Granularity of the description

• Do not gloss details with vague language. Subjects, objects, and verbs must be explicit.
• A phrase like "A uses B to do X" must specify what A is and why A is needed for X.
• Avoid vague verbs like "receives" or "passes". Spell out who does what to bring the state about (e.g. "receives the address" → "the platform allocates the address automatically").
• Do not require the reader to make a leap between steps. Every step's causal connection to the next is explicit.
• Describe the mechanism in its general form first; tie it to specific named instances afterwards as "in case X, ...". Do not anchor the whole description to a single proper-noun example.

Structure

1. Term list
2. Background (why this thing is necessary, or what problem it addresses)
3. Mechanism (how it works — includes the diagrams)
4. Concrete steps (commands, procedures, or worked examples)
5. Current state (where things stand today — for ongoing systems)