Information architecture
Follow the target structure for Azion documentation: the Platform Resource section skeleton, the order of the reader's journey, and where a new page goes.
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 Platform Resource. Each section holds one content type, so the journey decides where a section sits and the type decides what its pages look like.
The Platform Resource section skeleton
Every Platform Resource 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 in every section. A Platform Resource nested in another keeps no section of its own: it enters the parent resource’s section as a dropdown row in the slot-4 position, and its URL nests under the parent, as in /documentation/platform/firewall/waf/. The nesting rule and what the dropdown holds are in Nested Platform Resources.
| Order | Slot | Required | Holds |
|---|---|---|---|
| 1 | Overview | Yes | The section root page: what the Platform Resource is, what it does, when to use it |
| 2 | Quickstart | Yes | Quickstart pages: from not using the Platform Resource to the smallest working result |
| 3 | How it works | When the Platform Resource needs explaining | Concept pages: the mechanism, the tradeoff, how to choose between options |
| 4 | Features | When the Platform Resource has feature surfaces, or nested Platform Resources | The resource’s own sub-surfaces, such as a rules engine, Tiered Cache, or a runtime API, and the dropdown rows of the Platform Resources nested in it |
| 5 | Guides and tutorials | When the Platform Resource has tasks | One navigation hub listing the how-to guides and the tutorials |
| 6 | Examples | Functions only | Working code the reader copies, grouped by language or by task. A worked configuration for any other Platform Resource is a how-to guide in the Guides catalog, listed by the resource’s Guides and tutorials hub |
| 7 | Reference | When the Platform Resource has settings | Reference pages: fields, values, defaults |
| 8 | Limits | When the Platform Resource has limits | The limits table, dimensioned by plan |
| 9 | Best practices | Optional | How to run the Platform Resource well, and the reasoning behind each recommendation |
| 10 | Troubleshooting | When the Platform Resource has known symptoms | Troubleshooting pages: symptom, cause, fix |
| 11 | Glossary | Yes | Glossary pages: the terms the resource’s documentation uses, defined in a filterable table |
| 12 | Pricing | Yes | A link to the resource’s section of the pricing page |
| 13 | Changelog | Yes | A link to the resource’s changelog entries |
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, type, and last updated, 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 section.
The table is generated, not written. The date is the page’s last change and the type is the content type the guides catalog records for the page, 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 Platform Resource 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. It holds 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.
Limits, Pricing, and Changelog are rows of the section, at the same level as every other row, in slot order. They never share a parent such as Management.
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 Platform Resources
A Platform Resource nested in another is a dropdown row inside the parent resource’s 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, Origin Shield, and Live Ingest inside Connectors; Certificate Manager, Custom Pages, and DDoS Protection inside Workloads. On a page, its class is Platform Resource, whatever the naming catalog lists it as. It keeps only the pages that are its own: its reference pages, a Quickstart when it has a setup of its own, and, optionally, an Overview that the parent’s Overview links. When it has a mechanism to explain, its Reference group opens with a mechanism page: a concept page titled for the mechanism, such as Scoring and modes for WAF. Everything else the reader needs about it is written once, in the parent’s pages: what it does and when to turn it on in the parent’s Overview, a ## <Nested Platform Resource> section in the parent’s How it works that introduces it and links its mechanism page, its limits, practices, and symptoms in the parent’s Limits, Best practices, and Troubleshooting, its terms in the parent’s Glossary, and its guides in the parent’s hub.
A Platform Resource nests when its configuration lives in the parent resource’s own settings or rules: a flag in modules, a Rules Engine behavior, or a field of the parent. A Platform 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 Platform Resource, never a dropdown.
Quickstart carries the interface inside the page. A Platform Resource 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.
Platform onboarding, such as Creating an account in Fundamentals, is a different thing. Quickstart is the slot of one Platform Resource. Onboarding is the platform entry point, and it belongs to no Platform Resource.
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 Platform Resource needs only its reference pages, plus a mechanism page when it has a mechanism to explain and 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.
- The slot list is closed. 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. A fixed list is what lets the reader find the same slot in the same place in every section.
Pricing and limits
Prices come from the Pricing API, never from text. The Pricing page renders every on-demand price with the TablePricing component, which reads the API at build time.
- Pricing is a link, never a page. Slot 12 points at the resource’s section of the Pricing page, as in
/documentation/fundamentals/pricing/#<platform-resource>. Confirm the anchor resolves before you ship it. A nested Platform Resource has no Pricing row; the parent resource’s link covers it. - Never type a price, a quota, or a billing metric in a page. A page that shows on-demand prices renders
TablePricingwith theproduct_slugand themetric_slugof the Platform Resource. A typed price is wrong the day it changes. - Find the slugs in the API.
api/pricing/getlists every record, andapi/pricing/get/product_slug/<slug>returns one Platform Resource. Several slugs keep a deprecated name: Functions isedge_functions, Edge DNS isedge_dns, Real-Time Events isrealtime_events, and Load Balancer and Origin Shield shareconnector. Check the existingTablePricingcalls on the Pricing page before you add one. - The build depends on the API. A response that is not OK stops the build, so a failed build after a pricing change can be the API, not the page.
- Plans are not in the API yet. The current plans, their monthly price, and the usage each one includes come from the website. Link the plans page for plan prices and included usage, and never restate them.
- 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
## Limitssection in the reference page covers a short set.
Place a new page
Content that no single Platform Resource owns lives beside the Platform Resource sections, not inside one of them. Decide by the reader the page serves:
- The page documents one Platform Resource: place it in that resource’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 Use Cases, 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.