Multi-resource guides

Purpose

A multi-resource guide takes the reader to a goal that no single Platform Resource reaches. It applies the how-to base form.

Other documentation sets split this kind into solution guides, design guides, and implementation guides. This documentation uses one name and one set of rules, because the three describe the same page.

When to use

Write a multi-resource guide when:

• The goal needs two or more Platform Resources, and no Platform Resource section owns it.
• The reader thinks in outcomes, such as protecting a checkout, rather than in Platform Resource names.
• A guide for one Platform Resource keeps sending the reader to another Platform Resource mid-task.

Do not write a multi-resource guide when:

• One Platform Resource reaches the goal. Write a how-to guide in that Platform Resource’s section.
• The reader wants to understand the design rather than build it. Write an architecture page.
• The goal is a Use Case from the catalog. That is a use case, and it takes the same base form with an added scenario and a requirements table.

Register

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

Structure

Required components

• Problem opening: one or two sentences stating the problem, before any Platform Resource name. The Platform Resources, and the Products configured on them, enter after the problem, by role: “You configure caching on the application and request filtering on the firewall.”
• Prerequisites: a ## Prerequisites section, bulleted; each item is a link or a one-line command. A single prerequisite is a sentence, not a list.
• Stages: one ## per workflow stage, never per Platform Resource, each an imperative heading naming the stage. Each stage names its Platform Resource on entry, holds an ordinary procedure, and stands alone.
• Outcome sentence: every procedure ends by stating what the reader now has or sees.
• Next steps: a closing ## Next steps section, a DocCardGroup with one card per destination: the title, the link, and the reason as the card copy.

Optional components

• A Platform Resources table: what each Platform Resource contributes, when more than three are involved.
• A diagram: when the order of the pieces is hard to hold in prose. Link the architecture page instead when one exists.

Template

Copy the template and replace each <placeholder>.

Separate the major sections of the page with a --- rule, and never place one directly after the frontmatter.

Rules

• Title the goal, not the Platform Resources. The title states the goal in plain language, with no Platform Resource names: Serve a site with cached content and a protected checkout. The reader searches for the outcome.
• State the problem first. One or two sentences, then the Platform Resources, and the Products configured on them, by role: “You configure caching on the application and request filtering on the firewall.”
• Order by the workflow, never by the Platform Resource catalog. A page organized one Platform Resource at a time is a bundle of how-tos wearing one title.
• Name the Platform Resource at each stage. An unqualified interface name is ambiguous once the page crosses Platform Resources.
• Stay a how-to. The Platform Resources are the route, not the subject. A paragraph of Platform Resource background belongs to a concept page; link it.
• Follow the step rules. Steps follow Procedures, and every procedure ends with its outcome sentence.
• 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.
• Commit to one recommended path. Alternatives go in one aside, never as forks in the steps.
• Verify the whole path. These guides fail in the seams, so check the outcome and not the last step.
• Link the neighbors. Each Platform Resource’s how-tos and reference page, from the body or from ## Next steps.

Examples

This excerpt shows the problem opening, the prerequisites, and the first workflow stage:

Related