Skip to content

Documentation standards

Docs are the source of truth. Code or configuration and its documentation change together, in the same PR. If the docs don't say it, it isn't operationally true.

Structure

  • Each repo owns a MkDocs (Material) wiki under docs/, built with mkdocs build --strict (a required CI check — broken links and missing nav entries fail the build).
  • This repository, inva-documentation, is the central hub: architecture, infrastructure, systems, Emma, operations, security, inventory, development, decisions. Per-repo wikis hold the detail for their component and link back here.
  • A page has one home. Mirrored content names its source; do not fork the same facts across repos.

Every page carries front matter

```yaml

title: "…" owner: "…" status: "draft | active | deprecated" last_reviewed: YYYY-MM-DD review_cycle_days: NN classification: "internal | public"

```

Pages past their review cycle are revisited or retired; status reflects reality, not aspiration.

Writing rules

  • No secrets, ever — the wiki is scanned like code (gitleaks).
  • Cite, don't restate — link ADRs, inventory and runbooks rather than duplicating them.
  • Mermaid for diagrams (kept in the repo, diffable), tables for matrices, admonitions for warnings and gates.
  • Mark unknowns with the ⚠ placeholder; a deploy with unresolved markers is a bug.
  • Decisions become ADRs in docs/decisions/; they are immutable after acceptance except for status/superseded links.

Branding

All INVA wikis share one look: the INVA wordmark logo and favicon, the navy/teal brand palette and Inter type, from the authoritative brand system (inva-is/brand). Keep the theme block consistent across repos so the estate reads as one product.