Skip to main content
This page defines what content belongs on docs.optimism.io and, for every content type, which source is canonical. It exists so that “where does this live?” is settled by citing a rule, not re-argued in every pull request. Reviewers should link the relevant section of this page when requesting changes. The approach is adapted from the Kubernetes content guide, which governs kubernetes.io with the same two ideas: a short allowlist test for what the site hosts, and a strict preference for linking canonical sources over restating them.

​
What’s allowed: the three-clause test

Content belongs on docs.optimism.io only if at least one of the following is true (adapted from the Kubernetes content guide’s third-party content rules):
  1. It documents first-party OP Stack software — software whose source of truth lives in Optimism repositories, such as the components listed on the Releases page.
  2. It documents third-party software that the OP Stack needs to function — for example, an L1 execution client or key-management tooling that an OP Stack chain cannot run without. Such content must be marked with the <ThirdPartyContent> component.
  3. It routes to canonical content that lives elsewhere — a selection, orientation, or hub page whose job is to send readers to the right canonical home (for example, a curated matrix of SDKs that links each SDK’s own documentation).
Content that satisfies none of the three clauses — tooling promotion, project-specific marketing, or documentation for software that is neither first-party nor required by the OP Stack — belongs on the third party’s own site, not here. Wherever a canonical source already exists, link it — never restate it. The Kubernetes content guide states the reason plainly: dual-sourced content “requires double the effort to maintain and grows stale more quickly.” In practice:
  • Never paraphrase normative protocol text. Explain the concept in your own words at explanation depth, then deep-link the exact section of the OP Stack specifications for the normative definition.
  • Never copy reference material from another living document. If a component’s book, README, or upstream API reference already documents something, link to it.
  • Never fork a table of facts (versions, addresses, activation times, flag lists) that another system maintains. Render from the source of truth or link it.

​
Canonical homes

One home per thing. The matrix below assigns a canonical home to each content type across the three layers of the OP Stack documentation surface — the protocol, the components, and the periphery — and states what docs.optimism.io holds for each. Precedents for the matrix, clause by clause:
  • Spec joined, never mirrored. Kubernetes documents feature lifecycles through its structured feature gates reference rather than copying design documents into prose.
  • One identity page per component. ZKsync documents each service of its stack in a single canonical place (ZK Stack components); Cloudflare publishes a uniform per-product content strategy so every product’s documentation set has the same shape.
  • A curated matrix over the periphery. Stripe’s SDK page differentiates its client surfaces in one table; ethereum.org publishes written listing criteria so curation is policy application rather than per-PR debate.
  • The component declares its docs home. Each component’s README should point at its canonical documentation, following the op-deployer README model.
When two pages could both claim a topic, the matrix decides. If the matrix does not cover the case, raise it in the docs PR and propose a new row — amendments to this page go through the same review as any other docs change.

​
Marking third-party content

This section documents the <ThirdPartyContent> component, following the Kubernetes thirdparty-content shortcode pattern: every third-party mention is stamped the same way, so third-party content stays greppable and auditable.
Pages or sections that document or list third-party software (clauses 2 and 3 of the three-clause test) must open with the <ThirdPartyContent> component:
Which renders:
Items on this page refer to third-party projects or products that are not maintained by Optimism. They are provided for convenience; refer to each project’s own documentation as the source of truth.
When an entire page is about a single third-party project or product, use the single-project variant instead:
Which renders:
This page refers to a third-party project or product that is not maintained by Optimism. It is provided for convenience; refer to the project’s own documentation as the source of truth.

​
Next steps