From 88b5067c76a942dd3897a0514c814a9f76c1d938 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 16 Jul 2026 07:39:03 +0000 Subject: [PATCH] docs: add content-type contract pages for solution guide, learning unit, curriculum hub, and router/landing Publishes the content-type contracts introduced by the Paved Paths plan (Option C, slice 2): a spec page per new type (purpose, tone, required components, title grammar, copy-paste template, exemplars) plus a maintainer-facing disambiguation decision table. The new types are declared as compositions of the existing diataxis: frontmatter taxonomy via an optional content-type: key, extending the landed sweep rather than forking it. Tracks ethereum-optimism/solutions#961 Co-Authored-By: Claude --- docs/public-docs/docs.json | 10 ++ .../contribute/choose-a-content-type.mdx | 123 ++++++++++++++ .../op-stack/contribute/curriculum-hub.mdx | 141 ++++++++++++++++ .../op-stack/contribute/learning-unit.mdx | 132 +++++++++++++++ .../op-stack/contribute/router-landing.mdx | 120 ++++++++++++++ .../op-stack/contribute/solution-guide.mdx | 152 ++++++++++++++++++ 6 files changed, 678 insertions(+) create mode 100644 docs/public-docs/op-stack/contribute/choose-a-content-type.mdx create mode 100644 docs/public-docs/op-stack/contribute/curriculum-hub.mdx create mode 100644 docs/public-docs/op-stack/contribute/learning-unit.mdx create mode 100644 docs/public-docs/op-stack/contribute/router-landing.mdx create mode 100644 docs/public-docs/op-stack/contribute/solution-guide.mdx diff --git a/docs/public-docs/docs.json b/docs/public-docs/docs.json index ada3b5b25c8..17041986d9b 100644 --- a/docs/public-docs/docs.json +++ b/docs/public-docs/docs.json @@ -2388,6 +2388,16 @@ "pages": [ "/op-stack/reference/glossary" ] + }, + { + "group": "Contribute", + "pages": [ + "/op-stack/contribute/choose-a-content-type", + "/op-stack/contribute/solution-guide", + "/op-stack/contribute/learning-unit", + "/op-stack/contribute/curriculum-hub", + "/op-stack/contribute/router-landing" + ] } ] }, diff --git a/docs/public-docs/op-stack/contribute/choose-a-content-type.mdx b/docs/public-docs/op-stack/contribute/choose-a-content-type.mdx new file mode 100644 index 00000000000..2617dea2175 --- /dev/null +++ b/docs/public-docs/op-stack/contribute/choose-a-content-type.mdx @@ -0,0 +1,123 @@ +--- +title: Choose a content type +description: A maintainer-facing decision table for picking the right content type, and how the composed types extend the diataxis frontmatter taxonomy. +diataxis: reference +--- + +This page is for docs maintainers and contributors, not readers. It settles +the two questions that come up in almost every content pull request — "which +kind of page am I writing?" and "which frontmatter does it carry?" — by +decision table, so the answer is cited rather than re-argued per PR. The +pattern follows Cloudflare's maintainer-facing content-type selection page in +its [documentation content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/). + +Before choosing a type, check the +[content guide](/op-stack/contribute/content-guide) that the content belongs +on docs.optimism.io at all. + +## The taxonomy: four quadrants, four compositions + +Every page on docs.optimism.io carries a `diataxis:` frontmatter key with one +of the four [Diátaxis](https://diataxis.fr/) quadrant values — `tutorial`, +`how-to`, `reference`, or `explanation`. That taxonomy is complete and does +not grow: the composed types below are **compositions of the quadrants, not +new quadrants**, and they never appear as `diataxis:` values. + +A composed type is declared with a second, optional frontmatter key, +`content-type:`, carried *alongside* `diataxis:`. It takes exactly four +values, one per published spec: + +| Composed type | `content-type:` | `diataxis:` | What the composition is | +| --- | --- | --- | --- | +| [Solution guide](/op-stack/contribute/solution-guide) | `solution-guide` | `how-to` | A goal-scoped how-to at journey altitude: it sequences existing pages across quadrants and adds only the connective decision logic | +| [Learning unit](/op-stack/contribute/learning-unit) | `learning-unit` | The underlying page's quadrant (usually `explanation`; `tutorial` for hands-on stops) | A thin sequencing layer over one existing page inside an ordered track | +| [Curriculum hub](/op-stack/contribute/curriculum-hub) | `curriculum-hub` | `explanation` | An oriented index that composes all four quadrants for one feature under one sidebar node | +| [Router/landing](/op-stack/contribute/router-landing) | `router-landing` | Omitted — see below | Pure navigation: the page only routes readers to pages in the quadrants | + +Rules that keep this an extension rather than a fork: + +* **`content-type:` never replaces `diataxis:`.** Every page that documents, + instructs, or explains anything keeps its quadrant tag. The one sanctioned + omission is `content-type: router-landing`: a pure router contains no + documentation mode of its own to classify, so it carries `content-type:` + and no `diataxis:` key. If a router grows explanatory or instructional + content, it is no longer a router — reclassify it. +* **Only these four `content-type:` values exist.** Proposing a fifth means + amending this page and publishing a spec for it, through normal docs + review. +* **Pages of the four base types don't carry `content-type:` at all.** An + ordinary how-to is just `diataxis: how-to`. +* **`keywords.config.yaml` is not extended.** The composed types are + declared only in page frontmatter, per the rows above. + +## How-to guide vs. tutorial vs. solution guide + +These three are confusable because all three are action-oriented. The +distinctions are the starting state, the scope, and who owns the steps. + +| Question | How-to guide | Tutorial | Solution guide | +| --- | --- | --- | --- | +| What state does the reader start in? | A working environment, already set up | A clean machine (or close to it) — setup is part of the page | A working system, plus a goal that spans components | +| How wide is the scope? | One discrete task on one component | One end-to-end build, environment setup included | One goal across multiple components, often multiple documentation properties | +| Who owns the steps? | The page owns its steps | The page owns its steps | The page **derives**: each stop links an existing page and states what to extract; the page adds only decision logic | +| What does it end with? | Verification of the task | Verification of the whole working state, then cleanup | Verification of the outcome, then curated exits | +| Frontmatter | `diataxis: how-to` | `diataxis: tutorial` | `diataxis: how-to` + `content-type: solution-guide` | + +Quick tests: + +* If the page must install or configure the environment before the real + work starts, it's a **tutorial**. +* If the page's steps are its own — copy-pasteable commands the reader + executes on one component — it's a **how-to guide**. +* If the page's main job is sequencing *other* pages toward a goal and + deciding between options along the way, it's a **solution guide**. A + solution guide that starts restating the steps of the pages it links is + violating the [dual-sourcing ban](/op-stack/contribute/content-guide#link-dont-restate-the-dual-sourcing-ban) + — cut the restatement and link. + +Exemplars: [Configure the batcher](/chain-operators/guides/configuration/batcher) +(how-to at configuration-guide depth); +[Bridging your ERC-20 token](/app-developers/tutorials/bridging/cross-dom-bridge-erc20) +(tutorial); the first solution guide ships with the Use Cases section — until +it lands, the [solution guide spec](/op-stack/contribute/solution-guide) +carries the template. + +## Explanation vs. learning unit + +Both are understanding-oriented. The distinction is who the reader is and +what the page may assume. + +| Question | Explanation | Learning unit | +| --- | --- | --- | +| Who arrives? | Anyone, in any order, usually from search or a cross-link | A learner progressing through an ordered track or curriculum hub | +| What may it assume? | Only what it states in its own intro | Everything covered by the previous stops in its track | +| Who owns the content? | The page owns its conceptual material | The unit **frames** existing material: it adds sequencing context (what you now know, what this stop adds, where to go next) and links, never forks | +| Frontmatter | `diataxis: explanation` | The underlying page's quadrant + `content-type: learning-unit` | + +Quick tests: + +* If removing the page from its nav group would leave it fully + comprehensible, it's an **explanation**. +* If the page opens with "in the previous stop…" or only makes sense at + position N of a sequence, it's a **learning unit**. +* If you're about to *copy* an explanation into a track so you can reorder + it — stop. Learning units link and frame; they never duplicate. Add a + framing header to the existing page instead (see the + [learning unit spec](/op-stack/contribute/learning-unit)). + +Exemplars: [The OP Stack](/op-stack/introduction/op-stack) and the +[fault proofs explainer](/op-stack/fault-proofs/explainer) (explanations that +would gain learning-unit framing inside a track without being rewritten). + +## Next steps + +* Read the type spec before writing the page: + [solution guide](/op-stack/contribute/solution-guide), + [learning unit](/op-stack/contribute/learning-unit), + [curriculum hub](/op-stack/contribute/curriculum-hub), + [router/landing](/op-stack/contribute/router-landing). +* For the four base quadrants, the + [style guide's content types section](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/STYLE_GUIDE.md#content-types) + remains the reference. +* For what belongs on the site at all, see the + [content guide](/op-stack/contribute/content-guide). diff --git a/docs/public-docs/op-stack/contribute/curriculum-hub.mdx b/docs/public-docs/op-stack/contribute/curriculum-hub.mdx new file mode 100644 index 00000000000..71ee6455549 --- /dev/null +++ b/docs/public-docs/op-stack/contribute/curriculum-hub.mdx @@ -0,0 +1,141 @@ +--- +title: "Content type: curriculum hub" +description: The published contract for curriculum hubs — purpose, tone, required components, title grammar, and a copy-paste template. +diataxis: reference +--- + +A **curriculum hub** gathers everything a reader needs to master one feature +— fault proofs, interop — under a single sidebar node, ordered from gentle +introduction to normative spec. It is the answer to "I want to actually +understand X": one place, one reading order, all four documentation modes +composed for one topic. + +This page is the contract for the type. A new curriculum hub is reviewed +against it; cite the relevant section in review instead of re-arguing it. + +## Purpose + +* Give each major feature **one front door** with a recommended reading + order, instead of pages scattered across nav groups. +* **Compose, don't rewrite**: the hub resequences existing pages and adds + at most a few short learning-unit pages where the sequence has a gap. +* Make the exits explicit: every hub ends at the **normative spec** (and + audits, where they exist) so depth-seekers are routed off-site on + purpose, never stranded. + +## Composition + +A curriculum hub composes all four quadrants for one feature: explanation +(the gentle intro and deep dives), tutorial/how-to (the hands-on stops), +reference (component and configuration pages), and the spec exit. The hub's +index page carries `diataxis: explanation` (it orients the reader in the +feature) plus `content-type: curriculum-hub`. Stops inside the hub keep +their own quadrant values; new gap-filling stops follow the +[learning unit contract](/op-stack/contribute/learning-unit). + +See [Choose a content type](/op-stack/contribute/choose-a-content-type) for +how the composed types relate to the `diataxis:` taxonomy. + +## Tone + +* The index page orients: what the feature is, why it matters, and how + the materials fit together — in a few short paragraphs, not an essay. +* Every listed stop gets a one-line reason ("read this to …"), written + for the learner deciding whether to click, not as a summary. +* Confidence about order, honesty about depth: say what is skippable and + what is normative. + +## Required components + +Every curriculum hub must have: + +1. **One sidebar node**: the hub is a single nav group; a hub that spans + groups has failed its purpose. +2. **An index page** with frontmatter `title`, `description`, + `diataxis: explanation`, `content-type: curriculum-hub`, and + `last-reviewed: YYYY-MM-DD` (hubs are curated artifacts and enter the + review sweep on merge). +3. **An ordered path** on the index, in this shape (sections may be merged + or omitted only where the feature genuinely lacks the material): + * `## Start here` — the gentle introduction. + * `## Go deeper` — mechanism and architecture material. + * `## Get hands-on` — the tutorials and how-tos, where they exist. + * `## Economics and incentives` — where the feature has them. + * `## The normative spec` — deep links into + [specs.optimism.io](https://specs.optimism.io/) on **current spec + paths** (never retired path generations), per the + [content guide](/op-stack/contribute/content-guide). + * `## Audits and security` — where audits exist. +4. **One-line reasons** on every link. +5. **No duplicated content**: the hub links existing pages; a stop needing + rework gets an issue, not a fork. Gap-filling stops are new + [learning units](/op-stack/contribute/learning-unit), capped at a few + per hub. + +## Title grammar + +The hub's nav group and index title are the feature's plain name in sentence +case: "Fault proofs", "Interoperability". No "hub", "curriculum", "guide to", +or "learn" in the title — the shape is visible from the sidebar; the name +should match what readers search for. + +## Template + +Copy this template for a new hub's index page: + +```mdx +--- +title: +description: +diataxis: explanation +content-type: curriculum-hub +last-reviewed: +--- + + is, why it matters to this +audience, and how the materials below fit together.> + +## Start here + +* []() — read this first for the mental model. + +## Go deeper + +* []() — . +* []() — . + +## Get hands-on + +* []() — . + +## Economics and incentives + +* []() — . + +## The normative spec + +The definitive definition of behavior lives in the OP Stack +specifications: + +* [](https://specs.optimism.io/) — + . + +## Audits and security + +* []() — . +``` + +## Exemplars + +No hub is wired yet — fault proofs and interop are the first two planned. +Calibrate against the raw material and the external pattern: + +* The existing fault-proofs pages — + [explainer](/op-stack/fault-proofs/explainer), + [FP components](/op-stack/fault-proofs/fp-components), + [FP security](/op-stack/fault-proofs/fp-security) — the material a + fault-proofs hub resequences without rewriting. +* Arbitrum's [BoLD gentle introduction](https://docs.arbitrum.io/how-arbitrum-works/bold/gentle-introduction) + — the sidebar shape this type reproduces: gentle intro through deep + dive, economics, spec, and audits under one node. diff --git a/docs/public-docs/op-stack/contribute/learning-unit.mdx b/docs/public-docs/op-stack/contribute/learning-unit.mdx new file mode 100644 index 00000000000..5352cb252c4 --- /dev/null +++ b/docs/public-docs/op-stack/contribute/learning-unit.mdx @@ -0,0 +1,132 @@ +--- +title: "Content type: learning unit" +description: The published contract for learning units — purpose, tone, required components, title grammar, and copy-paste templates for both forms. +diataxis: reference +--- + +A **learning unit** is one stop in an ordered learning sequence — the "Learn +the OP Stack" track or a per-feature curriculum hub. It gives an existing +page a place in a syllabus: what the learner already knows on arrival, what +this stop adds, and where to go next. Content is linked and framed, never +duplicated. + +This page is the contract for the type. A new learning unit is reviewed +against it; cite the relevant section in review instead of re-arguing it. + +## Purpose + +* Let newcomers progress **linearly** through material that was written to + be read in any order. +* Add **sequencing context only**: orientation, prerequisites-by-position, + and a pointer to the next stop. +* Protect the underlying pages: a track that needs a page reworded forks + nothing — it files an issue against the page itself. + +## Composition + +A learning unit is a composition, not a fifth quadrant. It has two forms: + +* **Framing header** (the default): a short framing block prepended to an + existing page that serves as a track stop. The page keeps its own + `diataxis:` value; nothing else about it changes. +* **Standalone unit page** (the exception): a new short page written + because a sequence needs a stop that no existing page provides (for + example, a bridging paragraph between two concepts in a curriculum hub). + It carries the quadrant of what it actually is — usually + `diataxis: explanation`, or `diataxis: tutorial` for a hands-on stop — + plus `content-type: learning-unit`. + +See [Choose a content type](/op-stack/contribute/choose-a-content-type) for +the explanation-vs-learning-unit decision table. + +## Tone + +* Welcoming but not chatty; the learner is mid-sequence, so respect their + momentum. +* Second person, present tense: "you now know…", "this page adds…". +* The frame never editorializes about the underlying page ("this excellent + guide…") and never summarizes it — a one-line statement of what the stop + adds is the ceiling. + +## Required components + +**Framing header** (on an existing page): + +1. An `` block at the top of the page body, below the frontmatter and + any existing callouts. +2. Inside it, in order: the track name and stop position ("stop N of M"), + one sentence of arrival context (what the learner knows from previous + stops), one sentence of what this stop adds, and a link to the next stop + (or a completion line on the last stop). +3. Nothing else changes on the page: same `diataxis:` value, same content. + +**Standalone unit page**: + +1. **Frontmatter**: `title`, `description`, `diataxis:` (the quadrant of + what the page actually is), `content-type: learning-unit`. +2. **The same framing block** as above, so every stop reads uniformly. +3. **A body that earns its existence**: material no existing page owns. If + an existing page covers it, use a framing header on that page instead. +4. **A forward exit**: the last line links the next stop, or the track + index on completion. + +## Title grammar + +* A framing header adds **no title** — the underlying page keeps its own. +* A standalone unit page titles the concept as a plain noun phrase in + sentence case ("Fault proof economics", "From transactions to blocks"). + Position ("Part 3:", "Lesson 3") never appears in the title — order + lives in the track's nav group and the framing block, so stops can be + resequenced without retitling. + +## Templates + +Framing header — copy onto an existing page that becomes a track stop: + +```mdx + + ** — stop of .** + You've . This page . When you're done, continue to [](). + +``` + +Standalone unit page: + +```mdx +--- +title: +description: +diataxis: explanation +content-type: learning-unit +--- + + + ** — stop of .** + You've . This page . When you're done, continue to [](). + + + + +## Next stop + +Continue to [](), where you'll . +``` + +## Exemplars + +No track is wired yet — the learn track and curriculum hubs consume this +contract when they ship. Calibrate against the pages that would become +stops, and the external patterns: + +* [The OP Stack](/op-stack/introduction/op-stack) and the + [fault proofs explainer](/op-stack/fault-proofs/explainer) — existing + explanations that would gain a framing header, unchanged otherwise. +* [Bridging your ERC-20 token](/app-developers/tutorials/bridging/cross-dom-bridge-erc20) + — the shape of a hands-on stop (`diataxis: tutorial`). +* The [Rust Book](https://doc.rust-lang.org/book/) — the cadence this + type exists to reproduce: strictly ordered chapters, hands-on projects + spaced through the sequence, depth exiled to reference. diff --git a/docs/public-docs/op-stack/contribute/router-landing.mdx b/docs/public-docs/op-stack/contribute/router-landing.mdx new file mode 100644 index 00000000000..412c35dbcf5 --- /dev/null +++ b/docs/public-docs/op-stack/contribute/router-landing.mdx @@ -0,0 +1,120 @@ +--- +title: "Content type: router/landing" +description: The published contract for router and landing pages — purpose, tone, required components, title grammar, and a copy-paste template. +diataxis: reference +--- + +A **router/landing page** exists to send readers somewhere else, fast. The +site root routing four personas, a tab landing page, a goal-shortcut page — +all are routers: pure navigation with a one-line promise per destination and +nothing to read for its own sake. + +This page is the contract for the type. A new router is reviewed against it; +cite the relevant section in review instead of re-arguing it. + +## Purpose + +* Get every arriving reader onto the **right path in one decision**: + by persona (app developer, chain operator, node operator, protocol + learner) or by goal ("deploy a chain", "bridge an asset"). +* Order destinations by audience size, not internal org structure — the + largest audience's path comes first. +* Stay small: a router that starts explaining or instructing has stopped + being a router. + +## Composition + +A pure router is the one composed type that carries **no `diataxis:` key**: +it contains no documentation mode of its own to classify — it only routes +into pages that do. It carries `content-type: router-landing` instead, so it +remains machine-classifiable. The moment a page mixes routing with real +explanatory or instructional content, it is no longer a router: classify it +by what it teaches and move the routing into cards or a "next steps" +section. + +See [Choose a content type](/op-stack/contribute/choose-a-content-type) for +how the composed types relate to the `diataxis:` taxonomy. + +## Tone + +* Second person, benefit-first: every destination is phrased as what the + reader will accomplish, not what the section contains ("Deploy your + first contract on an OP Stack chain", not "Documentation about + contracts"). +* One line per destination. If a destination needs two sentences to + justify itself, the destination is wrong or the router is explaining. +* No marketing register. A router is wayfinding, not a pitch. + +## Required components + +Every router/landing page must have: + +1. **Frontmatter**: `title`, `description`, + `content-type: router-landing`, and `last-reviewed: YYYY-MM-DD` + (routers are curated artifacts and enter the review sweep on merge). + No `diataxis:` key — see Composition. `mode: wide` is allowed where the + layout needs it. +2. **At most one short orienting paragraph** (or a hero block) before the + routes. No concepts, no history, no feature tour. +3. **Routes as ``/`` blocks** (or an equivalent visually + scannable pattern), each with a title naming the reader or goal, an + `href`, and a one-line benefit. +4. **Full coverage of its audience split**: a persona router routes every + persona it claims; readers outside the split get a catch-all route + (search, glossary, or support). +5. **Resolving links only** — a router is a chain of links and nothing + else, so every link must resolve; dead routes are release blockers, not + cleanup. + +## Title grammar + +* A **goal router** takes the goal as an imperative phrase in sentence + case: "Deploy the OP Stack". +* A **persona/section landing page** takes the audience or section's + plain name: "App developers". +* Never "Welcome", "Home", "Overview", "Getting started" as the full + title — the title should say where the reader is or what they came to + do. + +## Template + +Copy this template for a new router/landing page: + +```mdx +--- +title: +description: +content-type: router-landing +last-reviewed: +--- + + + + + + + + + + + + + + + + + +``` + +## Exemplars + +* The [site root](/) — today a single-persona landing page ("Deploy the + OP Stack"); its planned rewrite into a four-persona router is the + first page that must pass this spec. +* [The OP Stack](/op-stack/introduction/op-stack) — a hybrid worth + studying for the boundary: it routes with cards *and* explains, which + is why it is classified `diataxis: explanation`, not + `content-type: router-landing`. +* Cloudflare's [documentation content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/) + — the published-content-type pattern this contract follows. diff --git a/docs/public-docs/op-stack/contribute/solution-guide.mdx b/docs/public-docs/op-stack/contribute/solution-guide.mdx new file mode 100644 index 00000000000..59f4073b64c --- /dev/null +++ b/docs/public-docs/op-stack/contribute/solution-guide.mdx @@ -0,0 +1,152 @@ +--- +title: "Content type: solution guide" +description: The published contract for solution guides — purpose, tone, required components, title grammar, and a copy-paste template. +diataxis: reference +--- + +A **solution guide** takes a reader with a real goal that spans multiple +components — "tune my batcher costs", "run a fault-proof challenger" — and +sequences the existing documentation into one paved path. It is the page a +reader would otherwise have to assemble themselves from guides, reference +pages, specs, and READMEs across several properties. + +This page is the contract for the type. A new solution guide is reviewed +against it; cite the relevant section in review instead of re-arguing it. + +## 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](/op-stack/contribute/content-guide#link-dont-restate-the-dual-sourcing-ban). + +## Composition + +A solution guide is a composition of the existing taxonomy, not a fifth +quadrant: frontmatter carries `diataxis: how-to` (it is goal- and +action-oriented) plus `content-type: solution-guide`. See +[Choose a content type](/op-stack/contribute/choose-a-content-type) for how +it differs from a plain how-to guide and from a tutorial. + +## 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 + +Every solution guide must have, in order: + +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 + +` ` in sentence case, naming the reader's goal: +"Tune batcher costs", "Run a fault-proof challenger", "Choose your node +stack". No "How to" prefix, no gerunds ("Tuning…"), no component-first +titles ("op-batcher cost tuning"). + +## Template + +Copy this template to start a new solution guide: + +```mdx +--- +title: +description: +diataxis: how-to +content-type: solution-guide +last-reviewed: +--- + + + +## Is this guide for you? + +Use this guide if: + +* +* + +If you , see []() instead. + +## Before you start + +You should already have: + +* +* + +## Step 1: + + + +Read []() and take away: + +* + +## Step 2: + + + +| If ... | Choose ... | Because ... | +| --- | --- | --- | +| |