# 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](/en/documentation/style-guide/content/architecture/) 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](/en/documentation/style-guide/content/reference/). - The reader needs steps for a task. Write a [how-to guide](/en/documentation/style-guide/content/how-to-guides/) or a [tutorial](/en/documentation/style-guide/content/tutorials/). - The subject is how Products and Platform Resources combine into a Reference Architecture. Write an [architecture page](/en/documentation/style-guide/content/architecture/). 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](/en/documentation/style-guide/writing/sentence-structure/) holds the rules. ## Structure The title is `How works`, `About `, 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 ``: ```mdx import FrameBox from '@aziontech/webkit/frame-box' import ItemList from '@aziontech/webkit/item-list' import DocItem from '@aziontech/webkit/doc-item' ## ## <...> ## Related resources ``` ## 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](/en/documentation/style-guide/content/how-to-guides/) 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](/en/documentation/style-guide/content/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: ```mdx **Tiered Cache** is a Cache feature that adds a cache layer between Azion's distributed infrastructure and the origin servers. With Tiered Cache enabled for the application, content stays cached for longer periods and the origin receives fewer requests. Tiered Cache is designed for objects that can remain in cache for a long period of time. Tiered Cache is available on request: activation goes through the Sales team. Its behavior depends on five mechanisms: the cache layers, the second-layer region, the TTL requirements, the Bypass Cache limitation, and the purge order. ## Cache layers End users send requests to Azion's distributed infrastructure, where content is cached. Without Tiered Cache, a request that misses the first cache layer goes to the origin. Tiered Cache adds a second cache layer between that first layer and the origin servers. The tiered layer can answer a request that misses the first layer, so the request does not reach the origin. Content stays cached for longer periods, and the origin receives fewer requests. ``` ## Related - [Architecture pages](/en/documentation/style-guide/content/architecture.md): The same base form, for a design that spans products. - [Reference](/en/documentation/style-guide/content/reference.md): Where the settings and the limits belong. - [How-to guides](/en/documentation/style-guide/content/how-to-guides.md): Where the steps belong. - [Choose a content type](/en/documentation/style-guide/content/choose-a-content-type.md): The full catalogue of page kinds.