Overview pages
Write the Overview of a Platform Resource: the section root that says what the Platform Resource is, what it does, and when to use it.
Purpose
An Overview page is the root of a Platform Resource section. It states what the Platform Resource is, what it does, and when a reader would use it. It applies the reference base form.
Every Platform Resource has one. It is the page a reader lands on from search, from the sidebar, and from another Platform Resource that links to this one.
When to use
- Write one Overview for every Platform Resource, 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 custom firewall rules. That belongs in a reference page inside the Platform Resource section. A Platform Resource nested in another is not a feature: it can have an Overview page of its own, and the parent resource’s Overview links 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 three parts. First the Platform Resource:
**<Platform Resource>** is a <class> that <verb>s <what it does> <where and how on Azion>.That sentence names the resource, states its class, and stands on its own. The class isPlatform Resource, on the Overview of a section and on the Overview of a nested Platform Resource alike, per Documentation terminology. The sentence never leans on a concept the reader has not met yet, as “runs that code” does. Then the concept: one or two sentences saying what the class of thing is, for a reader who has never used one, with any market term defined in place. Then one sentence naming the concrete jobs people use it for, in the reader’s vocabulary, closing the block:Use <Platform Resource> 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
DocButtonlabeled Quickstart and a secondary one labeled<Platform Resource> reference. - The mechanism: where a request, an event, or a job crosses more than two objects before the Platform Resource runs, that chain as a
mermaiddiagram, then a numbered walk of at most six items. Open with what the reader would otherwise assume wrong, and say in the same sentence what happens instead:Creating a Function does not expose it: a request reaches it only through a Function Instance that a rule invokes. - The specimen: where the Platform Resource has a code artifact, a configuration object, or a request, one complete, minimal example of it, in full, right after the mechanism, or right after the CTAs when the page has no mechanism section. Two to four bullets name its parts, and one sentence says what prior knowledge transfers. A Platform Resource with no such artifact skips this section rather than inventing one.
- The resources: only on a Platform Resource that has other Platform Resources nested in it. For each nested one, say what it does on this resource and when the reader turns it on, in one or two sentences, the first stating its class:
<Nested Platform Resource> is a Platform Resource that…. Then point to where the reader goes to use it. This is what the reader needs to decide whether to open the nested Platform Resource, 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, aDocCardGroupindexed 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. A Console path inside a sentence counts too: state the setting instead, per Word choice.
- No quality adjectives. Say what the Platform Resource does and where it stops.
- The title is the Platform Resource name, a noun. Not “documentation”, not a gerund.
- Put the Platform Resource before the concept. The first sentence states the class of the Platform Resource and what it does on Azion; the concept sentences follow it. Cover the Platform Resource name in the concept sentences: what remains must be true of any vendor’s version of the thing.
- Make every word of position agree with the request path.
for,of,in front of,behind, andbeforeeach imply an arrow. Draw the arrows the sentence implies and compare them with the diagram of the page. Say the direction with the verb:processes the requests received by your Workloads.runs a reverse proxy for your Workloadsputs the Workloads behind the proxy, and the request goes the other way. - Choose a verb that covers everything the Platform Resource does. When a Platform Resource does two or more things at the same level, the first sentence states the role they share and the next sentence lists them:
**Applications** is a Platform Resource that processes the requests received by your Workloads. An Application can run serverless functions, act as a reverse proxy for your origins, or combine the two.Test the sentence against the smallest configuration the documentation shows. - Read the definition as a reader from the market. A developer who knows the vocabulary of other platforms reads a workload as what runs behind an entry point. When that reading says something untrue about Azion, reword the sentence so that it states the role or the direction. This is a way of reading, not a list of words to avoid.
- Tell a relation between two Platform Resources forward. The one that makes the connection is the subject, and the sentence runs in the order things happen:
An Application receives the requests of a Workload once that Workload's deployment sets that Application.The sentenceAn Application receives the requests of the Workloads whose deployment sets it.starts at the end and leaves two pronouns that point backwards. In Brazilian Portuguese, the verb takes its object in full:define essa Application, nevera define. - Choose the concept with care. Several Azion elements do different things under one name. When one market concept fits everything the Platform Resource does, explain that concept. When none does, explain each thing in a sentence.
- Name the Platform Resource that provides a concept. When another Platform Resource provides one of those things, the sentence that explains the market term names its instance right after the term, and keeps the explanation:
A serverless function is a Function, code run on demand at each request, with no server for you to provision. - Cut from the definition block what the reader does not need. Four kinds of sentence go: background the Platform Resource does not change, such as how a registry delegates a domain; the step the reader already assumes, such as a proxy opening its own connection to the origin; a point the block already made; and a contrast with something the page does not cover, such as
A log is the opposite view. - A use says what this Platform Resource adds. The uses sentence names the jobs this Platform Resource does that another one does not. On Functions, the use is “block requests with your own logic”, because Firewall already blocks requests by rule. A security Platform Resource names the public standard its pages document, such as the OWASP Top 10.
- Name the Platform Resource in the first sentence, 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 does the Azion Platform Resource do, what is the class of thing, how does it get called, what am I writing, which Products it hosts, what can it do and where does it stop, where do I go now. An outline that reproduces the Platform Resource’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, notWhat 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 Platform Resource 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 its three parts and the specimen, and leaves out the mechanism. The first sentence names the Platform Resource, states its class, and says what it does on Azion; the next ones explain what a function is to a reader who has never used one; the uses sentence closes the block; 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: