Documentation Standard — what docs exist, where they live, when they're required
:::note Map + pointer
This is the single view of the platform's whole documentation system — the FAANG documentation
taxonomy (Product · Architecture · Developer · API · Quality · Operations · Security/Compliance ·
Business/Lifecycle · AI) mapped onto the homes that already exist here, path-gated like the delivery
paths. The decision of record is the rule
.claude/rules/documentation-standard.md;
this page is its published map. Companion: the writing discipline (docs-as-map, verified-reality, the
Definition-of-Done gate) lives in
documentation.md.
:::
Two axes first (don't flatten them)
- Platform vs IS — a doc belongs to the Platform pillar (a shared capability, one copy) or the IS pillar (a business app, docs live with the product). See the pillar boundary in the Architecture Hub.
- Delivery path (A/B/C) — the doc burden scales to the work, exactly like the SA artefact set: a one-line fix writes ~nothing new; a new product produces the full set.
We do not impose a generic docs/01-07/ tree — it would duplicate the SA artefact set and fight the
docs-as-map model. The taxonomy is a path-gated checklist pointing at existing homes, plus one
canonical per-product skeleton (below).
The category map
🔴 required · 🟡 when it applies · — n/a.
| Category | Home of record here | A | B | C |
|---|---|---|---|---|
| 1 Product (PRD, stories, roadmap, UX, release notes) | BMAD prd.md + UX docs; roadmap = GitHub Project board; release notes = release-please CHANGELOG | — | 🟡 | 🔴 |
| 2 Architecture (C4, ADR, ERD, SDD) | the SA artefact set assembled as the SDD; C4 (diagrams-as-code); ADRs → auto-index; ERD → auto-generated | — | 🟡 | 🔴 |
| 3 Developer (README, CONTRIBUTING, setup, troubleshooting) | repo standardization + the zero→prod runbook | 🔴 | 🔴 | 🔴 |
| 4 API (OpenAPI, auth, errors, versioning) | committed openapi.yaml + L3 contract tests; SSO | — | 🔴 if it has an API | 🔴 |
| 5 Quality & testing (strategy, matrix, perf, security) | testing strategy (L0–L4) + the live QA gate | 🔴 | 🔴 | 🔴 |
| 6 Deployment & operations (CI/CD, runbooks, monitoring, DR, SLO) | delivery workflow + reliability (SLO register + Game Days + DR drills) | 🟡 | 🔴 | 🔴 |
| 7 Security / privacy / compliance (threat model, data-class, IR, audit) | SA threat model + P0–P3 classes + the IS obligations register + change-records | 🟡 | 🟡 | 🔴 |
| 8 Business / lifecycle (user/admin guide, postmortems, SLO dashboard, EOL) | postmortems + Grafana SLO dashboards + the EOL/cloud-adoption policy | — | 🟡 | 🔴 |
| 9 AI-specific (model card, lineage, eval, prompts, RAG, agent spec, LLMOps/FinOps) | the LLMOps standard + the AI-governance matrix + the AI-Act gate | — | 🔴 if it calls an LLM | 🔴 |
Known thin spots (fill on need, don't pre-create empty files): coding-standards, API error-catalogue + versioning policy, user/admin guides, risk register, model card + dataset lineage.
New practice 1 — requirement IDs + the traceability matrix (the enterprise signal)
Give every requirement a stable, observable ID (FR-### / NFR-### / SEC-### / AI-###) and thread
it requirement → architecture component → test file → pipeline stage → evidence in one matrix. It
answers the question that separates mature engineering from "it works on my machine":
If
SEC-001changes tomorrow, which components, tests, pipelines and docs must change?
Template:
docs/templates/traceability-matrix.md.
Worked reference (real IDs, real tests, real CI):
ktayl-core/docs/traceability-matrix.md
— note it also surfaces the requirements not yet tested, which is precisely the point of the exercise.
Fleet — products with a traceability matrix (auto-indexed)
This table is regenerated by scripts/gen-trace-index.py (weekly + on-demand) — any repo that commits
docs/traceability-matrix.md appears here on its own, same self-indexing pattern as the
ADR and
ERD indexes. Click through — each matrix also surfaces
its untested requirements.
| Product | Traceability matrix (click through) |
|---|---|
| ktayl-core | docs/traceability-matrix.md |
New practice 2 — the canonical per-product docs/ skeleton
One reconciled layout (SA artefact set + the category checklist, platform concerns linked not copied), so
products stop varying. Full tree:
docs/templates/product-docs-skeleton.md.
Reference products: ktayl-core (plain docs/) and retrieva (Docusaurus).
How a developer uses this
- Starting a product? Follow the zero→prod runbook; it already seeds the skeleton. For a Path-C product, produce the full SDD + the traceability matrix.
- Making a change? Pick the delivery path → the table tells you which docs to touch; update them in the
same PR (the Definition-of-Done gate, per
documentation.md). - Looking for a doc? The central site is the map: ADRs → decision records, schemas → ERD index, tests → testing strategy.