Skip to content
Documentation

ADR-020: Docs Folder Convention & IA

Decision

Every file under docs/ is placed by user intent into one of the six canonical domains, and its Storybook title is derived from that canonical folder. This record is the authoritative folder-placement list and the entry-point routing map for any “where does this live / where does this go” docs-IA question.

Key rules

  • Place files into one of the six canonical domains by user intent, not by the source team that produced them.
  • Storybook titles must match their canonical folder prefix (e.g., docs/runbooks/ → Docs/Runbooks/).
  • Deprecated areas (e.g., docs/devops/, docs/security/) must not receive new files — use the canonical replacement domain instead.
  • The Docs/ sidebar may go 4 levels deep; all other roots cap at 3 levels (consistent with ADR-016).
  • Only these orphans are allowed at the docs/ root: README.mdx, CONTRIBUTING.mdx, adr-*.mdx, adr-index.mdx, adr-frontmatter-schema.mdx, and docs-index.json.
  • Every artifact in templates/ must have a sibling .mdx explanation file of the same stem.
  • Use this record as the entry point when you are unsure which governance ADR applies to a docs or IA question. Skip straight to the downstream authority when the question is specific:
    • Root sections, story placement within a root, section landing pages (00- prefix), and sidebar collapse defaults → ADR-016.
    • Deprecated root / story governance → ADR-019.
    • Docs folder structure and placement → this record (ADR-020).

Why

A single intent-driven folder taxonomy keeps related docs discoverable regardless of which team authored them, and deriving Storybook titles from the canonical folder prevents sidebar drift. Capping depth and constraining root-level orphans keeps the tree shallow and scannable. This record reconciles two points to current dmwd-io practice. First, it absorbs ADR-020’s routing-map role: the standalone decision map is retired and its pointers are folded into the rules above, so there is one entry point, not two. Second, ADR-020’s targets — story-title creation, story placement, landing-page naming, and sidebar collapse — have since been consolidated into ADR-016, so the routing now points there rather than at the retired ADR-016, ADR-016, and ADR-016 numbers.

Applies when

You are creating, moving, or renaming any file under docs/, deciding its folder and Storybook title, or you are unsure which governance ADR owns a docs or IA question and need the routing map.

  • ADR-016 — Storybook IA & navigation (root sections, story placement, landing pages, sidebar collapse, depth cap).
  • ADR-019 — deprecated root governance.
  • ADR-018 — single MDX format.