Skip to content

ADR-0028: Documentation surface

  • Status: Accepted
  • Date: 2026-08-17
  • Deciders: El, Lachlan

Context

Documentation needs to be readable and navigable — searchable, with rendered diagrams — without becoming a second place where content is authored.

Every wiki-shaped tool (Wiki.js, Outline, BookStack, Confluence) stores content in a database behind an API. That content cannot be diffed, cannot be reviewed in a pull request, cannot be maintained by an AI collaborator working through git, and drifts from the repository within weeks. It is also another service to host, patch, back up and secure.

Hand-authoring HTML pages in the BOS Console has the same defect in a worse form: it creates a second copy of every runbook, and the prettier copy is the one people follow after it goes stale.

There is a second failure mode worth naming: a runbook has to survive the outage it is used in. A docs site that depends on the infrastructure it documents is not a runbook.

Decision

  1. Git is the sole source of truth. Markdown in docs/ is the artefact.
  2. MkDocs Material builds a static site from docs/, deployed to Cloudflare Pages behind Cloudflare Access, on docs.octopodia.com.au (ADR-0022) — its own origin, not iframed into another.
  3. The BOS Console renders and deep-links into docs. It never authors them. No edit button. The moment the Console can write documentation, it is the wiki this ADR rejects.
  4. The Console owns state; the docs site owns prose. Provisioning checklists, tenant records and completion timestamps are data in the Console (ADR-0011), each phase deep-linking to its anchor on the docs site. Neither duplicates the other.
  5. Diagrams: Mermaid for anything that changes when the code changes — topology, tenant plane, flow — because it diffs in a PR and renders in both GitHub and MkDocs. Committed SVG in docs/architecture/ for polished client-facing material, referenced relatively so both surfaces resolve it.
  6. The whole docs/ tree publishes. It is all internal and behind Access; a curated subset is a maintenance decision that must be re-made forever.
  7. The repository path stays documented in AGENTS.md, so the markdown is findable when the rendered site is not.

Consequences

One authoring surface, two reading surfaces. Documentation changes go through the same review path as code, sit beside the ADRs they cite, and remain maintainable by an AI collaborator via PR. Runtime cost is effectively zero and there is no service to operate.

Because the markdown is the artefact, a runbook remains readable from GitHub, from a local clone, or via cat on the box during the incident it was written for.

The cost is that authoring stays a git workflow — there is no browser-based editing for anyone who would prefer it. That is the deliberate trade.

The existing hand-built HTML guides in docs/guides/html/ are presentation artefacts, not documentation, and are unaffected. They must not be extended into a parallel documentation set.

Alternatives considered

  • A wiki (Wiki.js, Outline, BookStack, Confluence) — rejected: database-backed content is not diffable, not PR-reviewable, not maintainable by an AI collaborator, and is another service to secure and back up.
  • Docusaurus / Astro Starlight — capable, but a React build and dependency tree where MkDocs is a pip install and one mkdocs.yml. Less to maintain is the point.
  • Hand-authored HTML pages in the Console — rejected: a second copy of every runbook, and the prettier copy wins.