Skip to main content
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. Before choosing a type, check the 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 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: 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. 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 — cut the restatement and link.
Exemplars: Configure the batcher (how-to at configuration-guide depth); Bridging your ERC-20 token (tutorial); the first solution guide ships with the Use Cases section — until it lands, the solution guide spec carries the template.

​
Explanation vs. learning unit

Both are understanding-oriented. The distinction is who the reader is and what the page may assume. 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).
Exemplars: The OP Stack and the fault proofs explainer (explanations that would gain learning-unit framing inside a track without being rewritten).

​
Next steps