Information architecture

This page defines the target structure for the Azion documentation. New sections follow it, and existing sections converge on it as they are revised. Do not copy the structure of an existing section: this pattern wins.

Two principles organize everything. Sections follow the order of the reader’s journey with the product. Each section holds one content type, so the journey decides where a section sits and the type decides what its pages look like.

The product section skeleton

Every product section follows this order. The table shows what each slot holds and when it exists.

A Platform Resource type with a section of its own (Workloads, Edge DNS, Applications, Connectors, Firewall) follows the same skeleton. Its Overview describes the resource type, its Quickstart creates the first instance, and Glossary, Pricing, and Changelog are required as they are for a product. A Product enabled on the resource keeps no section of its own: it enters the resource section as a dropdown row in the slot-4 position, and its URL nests under the resource, as in /documentation/platform/firewall/waf/. The nesting rule and what the dropdown holds are in Nested Products.

Two slots have a fixed sidebar shape.

Guides and tutorials is one row that opens a page. The row points at a hub whose body is a single table: name, last updated, and difficulty, one row per guide and per tutorial. The sidebar never expands it, and the reader opens a guide from the table. A section with forty guides stays one sidebar row, so the sidebar keeps showing the whole product.

The table is generated, not written. The date is the page’s last change and the difficulty comes from the page’s difficulty frontmatter field, so the hub cannot drift from the pages it lists.

Reference is a fixed group. The sidebar shows a Reference parent holding one row per reference page. The group name is the same in every product section, so the reader finds the fields in the same place everywhere.

Other rows may group the same way. A group is a menu parent, not a page, and it stays one level deep. Two modes exist:

• Fixed groups hold one slot’s pages under the slot’s standard name. Reference is the canonical case. Quickstart groups the same way in the one case it still splits: a first run an interface cannot share.
• Same-type groups hold related closing pages under one thematic parent. Management holds Limits, Pricing, and Changelog: the pages the reader consults about running the product.

Do not group rows that read fine flat. A parent costs the reader one click on every visit, so a group must pay for itself.

A feature with its own surface repeats the pattern one level down: Tiered Cache under Cache, with the same skeleton reduced to the parts it needs.

Nested Products

A Product enabled on a Platform Resource is a dropdown row inside the resource section, in the slot-4 position, with no group label: WAF, Network Shield, and Bot Manager inside Firewall; Cache, Application Accelerator, and Image Processor inside Applications; Load Balancer and Origin Shield inside Connectors; Certificate Manager, Custom Pages, and DDoS Protection inside Workloads. The Product keeps only the pages that are its own: its reference pages and, when it has a setup of its own, a Quickstart. Everything else the reader needs about it is written once, in the resource’s pages: what the Product does and when to turn it on in the resource’s Overview, how it works in the resource’s How it works, its limits, practices, and symptoms in the resource’s Limits, Best practices, and Troubleshooting, its terms in the resource’s Glossary, and its guides in the resource’s hub.

A Product nests when its configuration lives in the resource’s own settings or rules: a flag in modules, a Rules Engine behavior, or a field of the resource. A Product or resource the reader consumes from code (Functions, Object Storage, SQL Database, KV Store, AI Inference) and a standalone service (Edge DNS, Data Stream, Orchestrator) stay at the root of Platform resources. A feature is a page inside its Product, never a dropdown. A Platform Resource type nested in another, such as Certificate Manager and Custom Pages in Workloads, follows the same rule.

Quickstart carries the interface inside the page. A product whose first run goes through Azion Console, the Azion CLI, or the API keeps one page and selects the interface with tabs, so the slot holds one row and one URL. The slot splits only when the interfaces cannot share one stage skeleton, and for an AI agent, whose path is driven by prompt and shares no stage with the others. Those pages group under Quickstart, with Console first; the group is a sidebar parent, not a page. Quickstart pages holds the test.

The platform onboarding section at /documentation/get-started/ is a different thing with a similar name. Quickstart is the per-product slot. Get started is the platform entry point, and it belongs to no product.

Order, and what earns a slot

• The order mirrors adoption. A slot never moves ahead of its stage.
• Pricing and Changelog close the section. The reader consults them rather than passing through them.
• The Required column decides what ships. Every other slot exists only when real content fills it. The column applies to a section; a nested Product needs only its reference pages, plus a Quickstart when it has a setup of its own.
• Never add a slot to complete the pattern, and never keep an empty one as a placeholder.
• Grow by splitting a slot the section already has: Guides and tutorials into named task groups on the hub page, Features by surface. Quickstart grows inside its page, by interface tabs, and splits only when the stages cannot be shared.
• The thirteen never grow in number.

Pricing and limits

• Pricing is a link, never a page. Slot 12 points at /documentation/fundamentals/pricing/#<product>. Confirm the anchor resolves before you ship it. A nested Product has no Pricing row; the resource’s link covers it.
• Never restate a price, a quota, or a billing metric in a product page. A duplicated price is wrong the day it changes.
• Name the plan when availability is part of behavior, and link pricing for the numbers.
• Limits are dimensioned by plan. A single number hides the difference from every reader on another plan.
• The limits table contract lives in Reference: units, defaults, and raisable limits.
• Limits take slot 8 when the set is worth consulting alone. A ## Limits section in the reference page covers a short set.

Place a new page

Content that no single product owns lives beside the products, not inside one of them. Decide by the reader the page serves:

• The page documents one product: place it in that product’s section, in the slot its content type indicates.
• The page explains the platform, accounts, or billing: it goes in Fundamentals.
• The page diagnoses platform problems or reaches the support team: it goes in Support.
• The page builds a Use Case from the catalog: it is a use case, and it goes in Guides, under the Solution area of its entry.
• The page shows one Reference Architecture from the catalog, how Products and Platform Resources combine into a design: it goes in Architectures, under its Solution.
• The page collects links for an area: it is a navigation hub, and it needs a real audience before it exists.

When no section fits, open an issue before you create one. A new section changes navigation for every reader.