Multi-product guides

Purpose

A multi-product guide takes the reader to a goal that no single product 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-product guide when:

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

Do not write a multi-product guide when:

• One product reaches the goal. Write a how-to guide in that product’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 product name. The products, and the resources they are configured on, 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 product, each an imperative heading naming the stage. Each stage names its product 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 products table: what each product 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 products. The title states the goal in plain language, with no product 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 products and their resources by role: “You configure caching on the application and request filtering on the firewall.”
• Order by the workflow, never by the product catalog. A page organized product-by-product is a bundle of how-tos wearing one title.
• Name the product at each stage. An unqualified interface name is ambiguous once the page crosses products.
• Stay a how-to. The products are the route, not the subject. A paragraph of product 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 product’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