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

Documentation pages on docs.optimism.io carry 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 for composed types. The composed types are declared only in page frontmatter, per the rows above.

​
Notice metadata

A notice is time-bound operational content for an upgrade, deprecation, or other change that requires readers to prepare. Its dominant reader need is authoritative information about a specific change, so a notice carries diataxis: reference. The additional content_type: notice metadata key (with an underscore) marks the page’s operational purpose and lifecycle for the notice index and site search. It does not create a fifth quadrant or composition. The content-type: key (with a hyphen) remains limited to the four composition values above. Use a notice when the page must answer all of these questions:
  • What is changing and why?
  • Which personas are affected, and what breaks or remains compatible for each one?
  • What must each affected reader do before the cutover?
  • When and how does the change take effect?
After the change is complete, archive the notice and move durable facts into the relevant guide, reference, or network upgrade registry.

​
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