Choose a content type

Pick the form by the reader’s goal

Every documentation page is written in one of four base forms, from Diátaxis. The form decides the structure of the page and its sentence rules. Pick the form by what the reader wants to do, not by what you want to write about.

The forms answer “how do I write this page”. The page-kinds catalog answers “which page do I build”.

The page kinds

A page kind is a base form plus a place in the information architecture and a template. This is the complete catalog. Every page in the documentation is one of these kinds.

Required per product means required per section. A Product nested as a dropdown in a Platform Resource needs only its reference pages, plus a Quickstart when it has a setup of its own; every other page it would have is a section of the resource’s pages. The nesting rule is in Information architecture.

Slots are not kinds

A slot is a position in a product section; a kind is the shape of a page. The information architecture lists thirteen slots, and this catalog holds thirteen kinds. Equal length is a coincidence: the two lists do not map onto each other.

Several slots share one kind. Limits, Examples, and Features all hold reference pages, placed in different slots because readers reach them at different moments. Best practices and How it works both hold concept pages. One slot can also hold several kinds: Guides and tutorials holds a navigation hub, the how-to guides, and the tutorials. Adding a slot never adds a kind, and a page that fits no kind is a page whose content type is still undecided.

Kinds Azion does not use

Some kinds common in other documentation sets are deliberately absent, because each dissolves into the catalog:

• FAQ: a list of questions is a list of pages in disguise. Route each answer to its kind, and the question becomes a heading a search can find.
• Configuration: examples of settings and values are reference content. The kind adds a second name for the same page.
• Design, implementation, and solution guides: three names for content the catalog already holds. A goal that crosses products is a multi-product guide. A Use Case from the catalog, built end to end, is a use case. The reasoning behind a design is a concept or an architecture page.
• Third-party integration guide: a how-to guide that crosses a vendor’s interface. The third-party rules cover it.
• Solution page: a Solution lives on the website, not in the documentation. Here a Solution is the label of a Guides area and of an Architectures group. The pages are the use cases and architectures under it.
• API guidelines are not covered by this guide yet.

Separate tutorials from how-to guides

Tutorials and how-to guides both contain steps. They serve opposite readers, and this is the distinction that matters most.

A tutorial reader does not yet know what they want. They learn, and you teach. You choose the goal, you guarantee the result, and you keep decisions away from the reader. “Deploy your first application” is a tutorial: the reader has no application in mind, and any application will do.

A how-to reader already knows what they want. They arrived with a problem. You remove obstacles; you do not teach. “Configure cache policies” is a how-to: the reader has a cache problem and wants it gone.

Two tests separate the forms in practice. If you write “you can also” or “depending on your setup”, the page is a how-to, because tutorials do not branch. If you interrupt the steps to explain what a bucket is, the page is a tutorial or a concept page, not a how-to.

Separate reference from concept

Reference and explanation both describe; neither form instructs. They differ in use: one is a map the reader consults, the other is a discussion the reader reads.

Reference is the map. It is complete, consistent, and deliberately plain. Nobody reads a reference from top to bottom. If a reader who scans for a limit value skips a sentence, that sentence does not belong on the page.

Explanation is the discussion. It provides context, alternatives, and reasons. It is the only form where “why” and “instead of” belong. A design decision, a comparison between approaches, or the background of a feature lives in a concept or architecture page and nowhere else.

Separate multi-product guides from use cases

Both take the how-to base form and both cross products, so the split is worth stating.

A multi-product guide starts from a technical goal. The reader knows what they want to build and needs the route across products. It ends when the task is done.

A use case starts from a catalog entry: a customer situation the Use Case catalog already names and places under its Solution. The reader arrives with a situation, not a task. The page names the products the scenario needs, shows the architecture, configures it, and proves it works. It is written as a specification an agent can execute. That is why it carries a requirements table and a measurable outcome, which the multi-product guide does not.

The test runs in two steps. First match the goal to the Use Case catalog: an entry makes the page a use case, whatever the wording of the goal. With no entry, a goal the reader states without a customer situation is a multi-product guide. A customer situation the catalog should carry is a proposal for a new entry, not a page.

Keep one form per page

A page that mixes forms is the most common structural defect in documentation. A reference page that stops to walk the reader through the Console is two pages in one file. So is a how-to that pauses to explain architecture, or a tutorial that turns into a parameter table halfway down.

The test is cheap: read the page once as each of the four base-form readers. If two of them each want a different half, it is two pages. Split it.

Link the forms to each other

One form per page works because links connect the pages. Each form links out in a predictable direction.

Two rules keep the links checkable:

• Every page closes with links. A page ends with the closing its kind requires, ## Next steps or ## Related resources, holding at least one link to a documentation page. Glossary, changelog, and navigation hub pages are the exceptions, because each is a list of links already.
• No dead ends. At least one closing link leads deeper into the page’s own product: a page of that product other than its overview. A closing whose links all point back to where the reader came from is a dead end wearing a closing section.

Reciprocity is required only on the product spine: the overview links every page of its section, and every page of the section links the overview. Between any other two pages a link runs one way.

Read every content-type page the same way

Each page in this section describes one content type or pattern, and all of them use the same sections in the same order. Once you know where a rule lives on one page, you know where it lives on all of them.