Skip to main content
This document defines the minimum standard for documentation in this repository. It is intentionally operational: it prioritizes clarity, correctness, and maintainability over prose.

​
Goals

  • Make docs verifiable (reviewers can confirm correctness from sources).
  • Keep docs modular (avoid duplication; prefer shared snippets and canonical references).
  • Prevent drift between docs and the system (generated/reference-first for specs).
  • Scale across multiple services and repositories with predictable structure.

​
Scope and audiences

This repo contains multiple audiences. When writing or reviewing, be explicit about which audience a page serves.
  • Customer: product usage and workflows (non-technical or lightly technical)
  • Developer: integration, API usage, SDKs, service architecture
  • Enterprise: deployment, compliance/security posture, operations at scale
  • Internal: engineering/operations runbooks, ADRs, deep design specs
A page should not try to serve two audiences unless it clearly separates sections.

​
Document types and required sections

Use the simplest doc type that fits the intent.

​
Overview (“what is this?”)

Required:
  • Purpose (what it is)
  • Who it’s for
  • How it fits (links to related concepts/guides/reference)

​
Concept (“how does it work?”)

Required:
  • Problem / motivation
  • Core model (entities, invariants, state machine if applicable)
  • Failure modes (what can go wrong; guarantees and non-guarantees)
  • Related references (schemas, endpoints, events)

​
Guide (“how do I do X?”)

Required:
  • Prerequisites
  • Steps (ordered, copy/paste friendly)
  • Expected outcomes (what success looks like)
  • Troubleshooting (common errors and fixes)

​
Reference (“exactly what is supported?”)

Required:
  • Canonical source link (OpenAPI, proto, event schema, config)
  • Versioning policy (or link to it)
Rule: if the content is already expressed in a machine-readable spec, do not re-type it. Instead, render it (generated) or link to it.

​
Runbook / Operations

Required:
  • Signals (metrics/logs/traces, dashboards)
  • Playbooks (diagnosis → mitigation)
  • Rollback / recovery
  • Escalation (owners/contacts)

​
ADR (Architecture Decision Record)

Required:
  • Context
  • Decision
  • Consequences
  • Alternatives considered

​
Stub policy (definition + allowed markers)

A “stub” is any page that reads like a placeholder rather than usable documentation. A page is considered a stub if any of the following are true:
  • It includes obvious placeholder language such as: Stub, TODO, TBD, Placeholder.
  • It has headings without meaningful content under them.
  • It does not meet the required sections for its doc type.
  • It cannot be validated against a source of truth (links/specs/code) when it claims behavior.
Allowed markers:
  • DRAFT: in the first paragraph is allowed only if the page is still useful.
  • <!-- STUB --> is allowed for intentionally parked pages (should be rare and tracked).

​
Source-of-truth hierarchy (cross-repo scalable)

When information exists in a canonical system, docs should derive from it rather than duplicating it. Preferred order:
  1. Machine-readable specs: OpenAPI, protobuf, event schema definitions
  2. Executable examples: SDK samples, integration tests, reference clients
  3. Operational reality: runbooks + dashboards + incident learnings
  4. Narrative: concepts, overviews, guides
Practical rules:
  • Endpoint shapes, request/response bodies, status codes: OpenAPI.
  • Event names/payloads/versions: event schema source (and generation where feasible).
  • Wire formats and shared domain objects: protobuf.
  • Timeouts, limits, retries, idempotency: code + config, summarized with links.
If you must duplicate facts (e.g., to explain intent), keep it high level and link to the canonical spec.

​
Writing standards

  • Prefer precise language over marketing language.
  • State guarantees and non-guarantees explicitly.
  • Include version context when behavior is not timeless.
  • Avoid copying the same instructions into multiple pages; use snippets or link to the canonical page.

​
Verification standards (implemented as gates in CI)

These are the checks the docs system should be able to enforce:
  • No-stub gate: blocks known stub markers and missing required sections.
  • Broken link gate: mint broken-links clean.
  • Reference drift gate: generated reference output matches committed specs.
  • Build gate: docs preview/build succeeds.
(Automation is added later; this contract defines what automation must enforce.)

​
Change management

Documentation updates should ship with the change that requires them:
  • New endpoints/events/config knobs → update the canonical spec and regenerate reference pages.
  • Behavioral changes → update the concept/guide page and link the PR.
  • Incidents → update runbooks with the learning.
If a PR changes runtime behavior and does not update docs (or explicitly justify why not), it is incomplete.

​
Ownership model

Every documentation section has a primary owner who is accountable for accuracy. See OWNERS.md for the full ownership matrix, team aliases, and escalation paths. Key principles:
  • Ownership means accountability, not gatekeeping. Owners should enable contributions.
  • Changes to a section require approval from its primary owner (or secondary if unavailable).
  • Structure changes (navigation, new sections) require @docs-lead approval.
  • Stale content (not updated in 6 months while the system changed) should be flagged and assigned.