Concept pages

Purpose

A concept page builds understanding. The reader is not in the middle of a task; they want to understand how something works and why it is built that way, usually before deciding to use it.

It applies the explanation base form, one of the four Diátaxis forms. When Products and Platform Resources combine into a Reference Architecture, write an architecture page instead: it is the same base form with a diagram and a dataflow.

When to use

Write a concept page when:

• The reader wants the reason the product works this way, not the steps.
• A how-to guide grows a long preamble, or a reference page stops to justify a design.
• The page must compare alternatives and name a tradeoff.

Do not write a concept page when:

• The reader needs to look up a value, a field, or a limit. Write a reference page.
• The reader needs steps for a task. Write a how-to guide or a tutorial.
• The subject is how Products and Platform Resources combine into a Reference Architecture. Write an architecture page.

This is the page kind most often missing. When another kind starts to explain, write the concept page and keep that kind clean.

Register

Descriptive: 25 words per sentence, active voice, passive only where the actor is genuinely unknown or is the platform itself. Tone: explanatory, descriptive, even-handed, patient. Sentence structure holds the rules.

Structure

The title is How <X> works, About <X>, or a short noun phrase: How Tiered Cache works.

Required components

• Opening move: a declarative statement of how the system behaves, in the reader’s terms before any Azion object is named. Never This page explains.
• Roadmap sentence: the intro closes with one sentence naming the mechanisms the ## sections cover, in order.
• Mechanism sections: one noun-phrase ## per mechanism, mirroring the roadmap sentence.
• The problem, the mechanism, and the tradeoff: each section covers all three. An explanation that presents only upsides is marketing.
• Related resources: a closing ## Related resources section, a DocItem list linking the reference page and the how-tos that apply the concept, each row with its reason.

Optional components

• Key terms: the vocabulary the reader needs, defined once each.
• Alternatives: the other ways to solve the problem, and what each trades away.
• A diagram: when the relationship is easier to draw than to describe. Draw it as a mermaid code fence, and label every node in words.

Template

Copy the template and replace each <placeholder>:

Rules

• Open with behavior, not framing. State how the system behaves; never This page explains.
• Explain the thing before the Azion object. Cache stores a copy of a response in the data center that fetched it. That data center answers later requests for the same object from that copy, without reaching the origin. Only then the objects that realize it. An opening whose every subject is an Azion product or object is an inventory, not an explanation.
• Mirror the roadmap. One noun-phrase ## per mechanism, in the order the roadmap sentence names them. A section cut from the page is cut from the roadmap in the same edit.
• State the tradeoff. Every design choice costs something, so say what. An explanation that presents only upsides is marketing.
• No procedures. Link the how-to guide that applies the concept.
• Keep alternatives here. Alternatives and “instead of” live on concept pages and nowhere else.
• Use passive voice narrowly. Only where the actor is genuinely unknown or is the platform itself.
• Make diagrams carry load, and draw them in mermaid. A text diagram reaches an agent reading the markdown twin; an image does not. Say in prose what the diagram shows, and never rely on color alone.
• Discuss, do not enumerate. A page that becomes a table of fields wants to be reference.
• Define each term once, where the reader first meets it, then link to it.
• Avoid claims that expire. Currently and will soon age badly and nobody returns.

Examples

This excerpt of a concept page for Tiered Cache shows the opening move, the roadmap sentence, and the first mechanism section:

Related