Documentation structure
Documentation has one job: make the next correct decision easier.
Use the section that matches the kind of decision being documented:
| Section | Owns |
|---|---|
| Identity | Recognition cues: logo, voice, media kit, and reusable public brand assets |
| Foundations | Visual primitives: colour, typography, tokens, layout, accessibility, assets |
| Site governance | Durable rules: ownership, URLs, naming, content, privacy, quality, reuse |
| Site implementation | Mechanics: Hugo, Workers, components, patterns, shortcodes, tooling, generated output |
| Repository ADRs | Internal decision history, tradeoffs, consequences, and future follow-up |
Rule#
Put the rule where a reader needs to act on it. Keep the historical reasoning in an ADR when the decision changes the structure, ownership model, quality model, or technical boundary of the sites.
Boundaries#
- A brand asset belongs under Identity.
- A visual primitive belongs under Foundations.
- A rule that should survive a template rewrite belongs under Site governance.
- A template, partial, shortcode, script, Worker behaviour, or verification command belongs under Site implementation.
- A task-oriented composition of components belongs under Patterns; the durable rule for creating one belongs under Site governance.
- A decision record belongs in
/docs/adr/unless it has been rewritten as current guidance.
Maintenance#
When a page is difficult to place, name the decision first. If the page explains what should be true, it is usually governance. If it explains how the site currently makes it true, it is usually implementation.