Use cases

Purpose

A use-case page turns one entry of the Use Case catalog into a setup someone can build and verify. The entry gives the page its title, its scenario, its products, and the reference architectures it can build. The page never coins a use case of its own. The catalog is maintained by Azion. A writer who needs an entry, or finds one wrong, asks for it before writing the page. The request goes through the repository’s issue templates, or through the catalog’s owner inside Azion. The reader arrives with a situation, not a task: a storefront that slows down during a sale, a live event that has to reach one more region.

A use case is a specification, not an article. It carries everything an implementer needs in one page: the products the scenario requires, the architecture, the configuration, the checks, and the metrics that show it working. That implementer is often an agent, so the page is written to be executed rather than read.

Use cases live in the Guides section, never inside one product, under the Solution area of their catalog entry. The area’s label is the Solution name.

When to use

Recognize a use case by:

• A title that is a Use Case name from the catalog, verbatim: an imperative verb phrase naming a workload, with no product names.
• A reader who arrived with a business situation rather than a task.
• A requirements table mapping each business need to the product that meets it.
• An outcome that stays measurable after the setup works.
• A specification complete enough for an agent to execute without asking a question.

It is still a use case when:

• It configures four things or fewer. More than four means the entry is too wide for one page.
• It links the generic procedure instead of repeating it here.
• It ships without a demo, because none exists. Never describe a demo that does not run.

Write something else when:

• There is nothing to configure. The page explains a design, so write an architecture page.
• The setup is a single task. That is a how-to guide.
• The catalog has no entry for it, and the goal needs no customer situation. That is a multi-product guide. An entry makes the page a use case, whatever the wording of the goal.
• The reader has no scenario, only the product. That is a tutorial.

Register

Procedural: 20 words per sentence, one instruction per step, imperative and active. Tone: precise, plain, businesslike, sober. Sentence structure holds the rules.

Structure

Required components

• Scenario: three to five sentences from the catalog entry’s Scenario. They name the actor, the workload and the situation it is in, what this page sets up, and the measurable result. Followed by one line stating what the use case does not cover, the entry’s own exclusion.
• Prerequisites: a ## Prerequisites section, each item a link or a one-line command where one exists.
• Required products: the requirements table. One row per requirement, naming the technical need, the product that meets it, and the page that documents it. The Product column holds the Products of the catalog entry. A dependency the product documentation confirms and the entry omits goes in the table too, and the gap is reported to the catalog. The technical need names the platform resource the reader configures.
• Reference architecture: a ## Reference architecture section. It opens by naming which of the entry’s Reference Architectures the page builds, then holds a mermaid diagram and a numbered ### Dataflow. The entry’s other Reference Architectures are linked as architecture pages where one exists.
• Configuration: one ## Configure <thing> section per requirement whose setup is specific to this use case, four at most. Each holds a procedure that ends with its outcome sentence. A requirement met by a generic procedure gets no section. The requirements table links the guide that documents it, and the check stays in the verification section.
• Verification: a ## Verify the setup section with one check per requirement and its expected result.
• Measuring results: a ## Measuring results section naming the metrics that show the setup working, and where to read each one.
• Best practices: a ## Best practices section holding the recommendations and the reasoning behind each.
• Next steps: a ## Next steps closing, a DocCardGroup with one card per destination: the title, the link, and the reason as the card copy.

Optional components

• Demo: a ## Demo section linking a running example, a template, or a repository. Omit it when none exists; never describe a demo that does not run.

The sections keep this order. What governs the page is proportion, not length. A use case runs longer than other kinds by design: it is a specification, and an implementer working from it cannot fill a gap by asking. The page’s weight belongs in the sections an implementer executes:

• The configuration sections carry the page. Four at most, and together they are the largest part of it. If they are not, the page is describing a scenario rather than building one.
• Scenario, prerequisites, demo, and next steps stay brief. Each orients and hands off. A scenario that runs past a couple of paragraphs is selling.
• Reference architecture, verification, measurement, and best practices sit between the two. Each carries real content — a diagram, a check that runs, a signal to watch — and none of them is a place to expand.

The bound that keeps a use case honest is the four-section cap on ## Configure, not a length. Compression is never the fix, because what gets compressed is the diagram, the command output, and the concrete value — the parts an implementer cannot proceed without.

Template

Copy the template and replace each <placeholder>:

Rules

• Write a specification, not an article. Every value is concrete, every command runs, and no step says “depending on your setup”. The reader may be an agent, and an agent cannot resolve an ambiguity by asking.
• Show the output after every command. The reader sees what success looks like before the next step depends on it. The rule is in Procedures.
• Narrow the scenario to one buildable setup. State it as A <team> that <has this> configures <this setup> so that <this checkable outcome>. If the sentence needs an “and also”, the entry is too wide for one page. Write the first setup and report the width to the catalog. Do not coin a second use case.
• Start from the requirements table. Every row is a requirement you have confirmed against the product. A requirement you cannot confirm does not go in the table.
• Inline what is specific to this use case. Link what is true for every use case. The generic path is a link; the page holds what the scenario changes.
• Cap the configuration at four sections. A requirement met by a generic procedure never counts: its guide is linked from the requirements table, and its check stays in the verification section. More than four requirements that need a section of their own means the entry is too wide for one page. Narrow the setup to the Reference Architecture the page builds and report the width to the catalog. Never raise the cap, and never coin a second use case.
• Diagram in mermaid. The diagram is text so that an agent reading the markdown twin gets the design, not an image reference. The numbered dataflow still carries the meaning: the diagram never stands alone.
• Separate verification from measurement. Verification is a one-time check that the setup is correct. Measurement is the ongoing signal that it still works.
• Keep best practices as recommendations with reasons. A recommendation without its reason is an instruction in the wrong section, and it belongs in the procedure.
• Never make a commercial claim. No cost saving, no percentage, no competitor, no customer name, and no assertion that a configuration makes anyone compliant.
• Example figures are not limits. A figure that frames the scenario stays in the scenario paragraph and appears nowhere else.
• Take the title, the scenario, and the products from the catalog entry. A request that arrives as a bare scenario, such as e-commerce or live streaming, is matched to an entry first. An entry makes the page a use case, whatever the wording of the goal. When no entry covers it, a goal that needs no customer situation is a multi-product guide. A customer situation the catalog should carry is proposed as an entry first. A use case is never coined on the page.
• Never invent a product name, a field, or a value. Take product names from Documentation terminology, and fields and values from the product, not from a URL or a directory path.
• Report the permalink when the page ships, so the catalog entry’s Docs field can read Published.

Examples

This excerpt of the use case Build e-commerce storefronts builds its Origin-hosted commerce platform storefront reference architecture. It shows the scenario, the not-covered line, and the requirements table:

Each row names a requirement, the resource the reader configures, the Product that meets it, and the page that documents it. The reader can check every claim before running a single step.

Application Accelerator is not among the catalog entry’s Products. The Rules Engine reference confirms that the Bypass Cache behavior requires it, so the row carries it and the gap goes back to the catalog.

Related