Content type: solution guide

​

Purpose

• Turn a traced reader journey into one in-site page with curated exits, so the goal is completable without leaving docs.optimism.io except through exits the guide chose on purpose.
• Add the connective decision logic — which option to pick when, and why — that no single component page can own.
• Derive, never duplicate. Each stop links the canonical page and states what to extract from it. Restating a linked page’s steps or facts violates the dual-sourcing ban.

​

Composition

​

Tone

• Direct and economical. The reader has a goal and a working system; no scene-setting beyond the one-paragraph goal statement.
• Decisions are stated as conditions: “if X, choose Y because W” — never a bare “we recommend Y”.
• Honest about staleness: any exit into hand-maintained or version-pinned material carries an “as of” marker rather than implying freshness.

​

Required components

1. Frontmatter: title, description, diataxis: how-to, content-type: solution-guide, and last-reviewed: YYYY-MM-DD (solution guides are curated artifacts and enter the review sweep on merge).
2. Goal statement: one paragraph naming the outcome, the intended reader, and the components involved.
3. Fit test (## Is this guide for you?): bullet conditions for when to use the guide, plus where to go instead when it doesn’t fit.
4. Starting state (## Before you start): the working state and access the guide assumes. A solution guide never contains environment setup — that is tutorial territory; link one if needed.
5. Sequenced stops (## Step 1: …, ## Step 2: …): numbered ## sections, each an imperative action. A stop that derives from another page links it and states exactly what to extract. A stop that is a decision states the decision logic, preferably as an if/choose/because table.
6. Verification (final step): how the reader confirms the goal is reached.
7. Curated exits (## Curated exits): the deliberate ways out — deeper reference, the normative spec, upstream material — each with a one-line reason and, where the target is version-pinned or hand-maintained, an “as of” marker.

​

Title grammar

​

Template

---
title: <Verb> <object>
description: <One sentence naming the outcome and who it serves.>
diataxis: how-to
content-type: solution-guide
last-reviewed: <YYYY-MM-DD>
---

<One paragraph: the goal, the intended reader, and the components involved.>

## Is this guide for you?

Use this guide if:

*   <condition on the reader's role or system>
*   <condition on the goal>

If you <adjacent need>, see [<other page>](</path/to/page>) instead.

## Before you start

You should already have:

*   <working state this guide assumes>
*   <tools or access required>

## Step 1: <Imperative action>

<What to do. When this stop derives from another page, link it and state
what to extract:>

Read [<page title>](</path/to/page>) and take away:

*   <the specific values, concepts, or commands this goal needs>

## Step 2: <Imperative decision>

<The connective decision logic this guide adds — the material that exists
nowhere else:>

| If ... | Choose ... | Because ... |
| --- | --- | --- |
| <scenario> | <option> | <rationale> |

## Step 3: Verify the outcome

<How the reader confirms the goal is reached: the metric, output, or state
to check, and what a good result looks like.>

## Curated exits

*   [<Exit title>](<url>) — <what the reader gets there>. <As of `<tag or
    date>` for version-pinned or hand-maintained targets.>
*   [<Normative spec section>](https://specs.optimism.io/<path>) — <why a
    reader would need the normative definition>.

​

Exemplars

• Configure the batcher — the central stop of the batcher-costs journey: the depth a solution guide links into rather than reproduces.
• Consensus client configuration — in-site precedent for stated decision criteria between options.
• Cloudflare’s documentation content strategy — the published-content-type pattern this contract follows.