ADR 0009: Documentation structure
- Status
- Accepted
- Date
- Deciders
- Founder, product team
Context
Trovensa needs documentation for two audiences: the scientists, reviewers and operators who use the platform, and the team that builds it. Facts about routes, permissions, statuses and tokens must mirror the code exactly, and every page must have one job.
Decision
The docs site is a Nextra 4 static export organised by Diátaxis in two areas. Platform (customers and operators): tutorials, how-to, reference, explanation. Engineering: specs, design, decisions, roadmap, runbooks. Every _meta.ts is wrapped in definedPages() so a page appears the moment it exists and no placeholder page is ever published. Titles follow the type (“How to …”, “About …”, “ADR NNNN: …”, reference pages named as the code names the thing). Reference and specification pages end with a Source: line naming the files read. ADRs have five headings, are numbered in writing order, and are superseded, never edited. lib/content.ts mirrors the app’s products, stages, permissions and personas and types the chips against them; app/globals.css carries the same tokens as the web app and check-tokens compares them. Screenshots come from the web app’s shots runner as light and dark pairs.
Consequences
- The docs
checkaggregate (typecheck, brand, stubs, product names, tokens) runs before every hand-over andverify(build, link crawl, smoke) before every deploy. - Every capability page states the product status (
designed) and labels screenshots of seeded data illustrative. - The permissions page lists 72 keys in backticks and says “72 permissions” so the sync gate can read it.
Alternatives considered
- Docs inside the marketing site: mixes positioning with reference; rejected.
- A wiki: no gates, no code mirror; rejected.
Follow-ups
- none