Overview pages

Purpose

An Overview page is the root of a product section. It states what the product is, what it does, and when a reader would use it. It applies the reference base form.

Every product has one. It is the page a reader lands on from search, from the sidebar, and from another product that links to this one.

When to use

• Write one Overview for every product, as the first page of its section.
• Write it before any other page in that section. The Overview decides what the section is about.

Do not write an Overview when:

• The subject is a feature, such as Tiered Cache or Real-Time Purge. That belongs in a reference page inside the product section. A Product nested in a Platform Resource is not a feature, and it has no Overview page of its own: the resource’s Overview presents it.
• The page would walk the reader through a task. That is a how-to guide, linked from here.
• The page would only list links. That is a navigation hub.

Register

Descriptive: 25 words per sentence, active voice, passive only when the actor is unknown. Tone: inviting, factual, direct. Sentence structure holds the rules.

Structure

Required components

• Definition block, in two layers. First the concept: one or two sentences saying what the class of thing is, for a reader who has never used one, with any industry term defined in place. Then the product: **<Product>** <verb>s <the concept> <where and how on Azion>. Then one sentence naming the concrete jobs people use it for, in the reader’s vocabulary: Use <Product> to handle A, run B, or serve C. A bulleted benefit list is the weaker form of that sentence: it reads as a brochure and costs a screen.
• CTAs: a primary DocButton labeled Quickstart and a secondary one labeled <Product> reference.
• The specimen: where the product has a code artifact, a configuration object, or a request, one complete, minimal example of it, in full, within the first screen. Two to four bullets name its parts, and one sentence says what prior knowledge transfers. A product with no such artifact skips this section rather than inventing one.
• The mechanism: where a request, an event, or a job crosses more than two objects before the product runs, that chain as a mermaid diagram, then a numbered walk of at most six items. Open with what the reader would otherwise assume wrong.
• The resources: only on a Platform Resource that hosts Products. For each Product, say what it does on this resource and when the reader turns it on, in one or two sentences, then point to where the reader goes to use it. This is what the reader needs to decide whether to open the Product, never its feature list.
• The boundaries: one compressed bulleted block with bolded lead-ins — languages, APIs, frameworks, integrations, and the headline limits. One block, not one section per feature.
• Capability sections: only for a capability that changes what the reader would build, three at most. A capability that is one sentence and a link belongs in the boundaries block or the router.
• Closing: ## Next steps, a DocCardGroup indexed by what the reader wants to do: each card names the destination, and its copy is the intent (Run your first one now.).

The sections keep this order.

Template

Copy the template and replace each <placeholder>:

Rules

• Never instruct. No numbered steps, no procedures, no click-throughs. The specimen is not a walkthrough: it is shown once, complete, with nothing for the reader to do. An overview that instructs is a quickstart page filed wrong.
• No quality adjectives. Say what the product does and where it stops.
• The title is the product name, a noun. Not “documentation”, not a gerund.
• Explain the thing before the product. The first sentence says what the class of thing is; the product sentence follows it. Cover the product name: what remains must be true of any vendor’s version of the thing.
• Name the product by the second sentence at the latest, and never open on the problem space. A concept sentence explains a mechanism. A sentence about how important the problem is explains nothing.
• Organize by the reader’s questions, not by your feature list. The sections answer, in order: what is this and what does Azion’s version do, what am I writing, how does it get called, which Products it hosts, what can it do and where does it stop, where do I go now. An outline that reproduces the product’s feature list is a catalog: it answers “what do we sell” instead of “what am I deciding”.
• The questions shape the sections; they never become the headings. A heading is a short noun phrase, never a question: Function structure, not What a function looks like.
• Draw the diagram from the documented sequence. A diagram of a sequence the documentation already states in prose is a change of notation, not a new fact. Every node and every arrow matches a step the product performs, and the numbered walk carries the meaning if the figure does not render.
• Send the reader to the Quickstart, in the CTAs and again in the router.
• Never thin the specimen or drop the diagram to make the page shorter. They are the two things the reader came for. A page that runs long has grown capability sections; compress those into the boundaries block.

Examples

This excerpt of the Functions overview shows the definition block in two layers, then the specimen. The first paragraph explains what a function is to a reader who has never used one; the second names the product and what it does on Azion; the specimen shows the artifact instead of describing it:

The same page closes with the router, indexed by what the reader wants to do rather than by page title:

Related