Skip to content

Documentation standards

VerifiedOwner Documentation integratorLast verified onix-docs@a2-publication

These rules are enforced by the build wherever enforcement is possible. Where a rule cannot be automated, it is stated here so review has something concrete to check against.

Required front matter

Every page in docs/ must open with:

---
title: Sentence-case page title
summary: One sentence. Under 200 characters. Plain text, no markup.
status: verified
owner: backend
last_verified: 2026-09-02
source_pins:
  - backend@efa38e04e2db37a444e9f17100323c2ad4b83647
evidence:
  - "backend@efa38e04:docs/handoff/contract-manifest.json"
  - "backend@f80bc316:src/module/file.py"
---
Field Rule
title Required, non-empty. Must match the page's single level-1 heading.
summary Required, non-empty, under 200 characters, plain text.
status Required. Exactly one token from the status model.
owner Required. One of integrator, frontend, backend, native.
last_verified Required. ISO YYYY-MM-DD. The date claims were last checked, not the date the file was edited.
source_pins Required, non-empty list. The commits the page was written against.
evidence Required list of at least two repo@commit:path anchors. Each must resolve.

The build fails on any violation. The status strip and evidence block are generated from this metadata — never write either by hand.

Structure

  • One level-1 heading per page, matching title, as the first line of the body.
  • Heading levels descend without skipping.
  • Section headings are sentence case.
  • Tables are preferred to bulleted lists whenever the content has more than one dimension.
  • Diagrams use Mermaid fences. A diagram must not carry information that is not also in the prose, because a diagram is not accessible to every reader.
  • Target 700–1600 words for a substantive page. Index pages may be shorter. Length is not a goal; padding a page to hit a number is worse than a short page.
  • Internal links are relative and must resolve. Strict mode fails otherwise.
  • Link to the owning page rather than restating a definition. Duplicated definitions were the main source of drift in the documentation set this one replaced.
  • External links are permitted for upstream projects and standards. Do not copy their content; see upstream reference discipline.
  • Do not link to internal tooling, private hostnames, ticket systems or operational dashboards from a published page.

Language

  • Write for a competent reader who has never seen the codebase.
  • Prefer plain statements to hedged ones. Where genuine uncertainty exists, use the Unverified status or an inline marker such as *(production-record only; live host not observed)* rather than vague wording.
  • No marketing superlatives. No "powerful", "seamless", "world-class", "revolutionary".
  • No first-person plural advocacy. Describe the system, not the team's feelings about it.
  • Use British or American spelling consistently within a page; the site as a whole uses British spelling for prose and preserves American spelling in code identifiers.
  • Never use a retired brand name. The safety scan enforces this.

Claims

  • A present-tense claim about behaviour must be supported by an evidence anchor that a reviewer can open.
  • A claim about deployment must distinguish recorded from observed. If no live host was observed, the page says so and uses the Production record token.
  • A claim about a capability must state its availability honestly: private, internal, test-stage, preview, or generally available. In this system, almost nothing is the last of those.
  • This documentation does not claim live real-money execution, and does not describe multi-user identity and access control as complete.

Accessibility

  • Every image and diagram needs a text equivalent in the surrounding prose.
  • Tables get header rows; layout tables are not used.
  • Colour is never the only carrier of meaning — status badges carry a text label as well as a colour.
  • Interactive elements must be reachable and visibly focusable by keyboard.
  • Do not disable focus outlines.

Safety

Never publish: credentials, tokens, API keys, webhook secrets, signing identities, team identifiers, private hostnames, internal IP addresses, operational filesystem paths that reveal private topology, customer data, or the contents of private patches.

If a page needs one of those to be useful, it belongs in the quarantined internal set rather than on the public site. The reason for withholding is published even though the content is not; see the documentation model.

Evidence and source pins for this page

Verified. Current behaviour, confirmed in source at the pinned commit.

Verified on against the following immutable sources:

  • onix-docs:tools/docs_hooks.py
  • onix-docs:mkdocs.yml

Status tokens are defined on the documentation and status model page. Every pin on this site is listed under versions and source pins.