ADR 019: Documentation structure
- Status: Accepted
- Owner: Eng lead
- Date: 2026-11-13
Context
Root docs/ mixed integrator guides, platform internals (docs/platform/), dated reviews and implementation trackers. Status lived in several overlapping pages (implementation-progress.md, platform/review.md, testing-completion-criteria.md, platform-status.md), so completed and pending work drifted apart.
Decision
- Integrator guides stay at the top level of
docs/with unchanged URLs. SDK READMEs, Swift/Kotlin comments and error messages link to them. - Platform documentation is split into top-level sections, each a sidebar tab on the site:
architecture/,security/,deployment/,operations/,decisions/,implementation/andreviews/. - Each folder's landing page is
README.md(GitHub shows it;apps/docs/lib/source.tsmaps it to the folder URL). implementation/is the single tracker: one findings table with IDs and statuses in its README, pluscompleted.md,remaining-tasks.md,blockers.mdandchangelog.md. Reviews are dated and immutable once superseded; their still-open items move into the tracker rather than accumulating in review files.platform-status.mdremains the integrator-facing support matrix and must agree with the tracker.
Consequences
/docs/platform/* URLs moved to the new sections (/docs/deployment, /docs/architecture, …). Internal links were rewritten and are checked by apps/docs/test/content.test.mjs and the export link check.