Contributing to Documentation¶

Where to put a new doc¶

Each doc belongs to a primary audience. Pick the most appropriate folder under docs/audiences/:

smt/ — leadership, ≤ 2 pages each, plain English, no jargon
tech/ — internal engineering reference; deep technical detail expected
compliance/ — auditor / regulatory; factual, code-cited, evidence-led
integrators/ — external developers using our APIs (scaffold-only in v1)
procurement/ — commercial / vendor review (scaffold-only in v1)

If a doc serves multiple audiences, write it for the most-demanding audience and link from the others' index pages.

Diagrams¶

All diagram source files live in docs/diagrams/. Markdown docs reference the rendered SVG using a relative path. From a file at docs/audiences/<audience>/<doc>.md use ../../diagrams/<name>.svg; from a deeper file like docs/audiences/tech/services/<svc>.md use ../../../diagrams/<name>.svg.

Mermaid (.mmd) — for sequence, ERD, simple architecture diagrams
D2 (.d2) — for network topology and complex system diagrams

Update the source file; CI re-renders SVGs on every commit. Do not commit rendered SVGs to git.

Frontmatter convention¶

Every markdown file under docs/audiences/ should start with frontmatter:

---
title: Security Model
audience: compliance
owner: tech-lead
last_reviewed: 2026-04-27
review_cycle_days: 90
---

scripts/docs/check-staleness.sh will warn on docs whose last_reviewed exceeds review_cycle_days.

Generated artifacts¶

Files under audiences/*/generated/ are produced by scripts/generate-docs.sh. Do not edit them by hand — your changes will be overwritten on the next CI run.

To regenerate locally: bash scripts/generate-docs.sh.

Review cycles per audience¶

Audience	Default cycle	Owner
SMT	180 days	Tech lead
Tech	90 days	Service owner (or tech lead)
Compliance	90 days	Tech lead + DPO
Integrators	90 days	API owner
Procurement	180 days	Commercial team