Skip to content
Documentation

ADR-017: Documentation Truthfulness

Decision

Storybook stories and docs must tell the truth about the component: source is copy-paste-ready, the full prop contract and failure modes are shown, docs live in the folder that matches their sidebar location, and no table cell is left blank.

Key rules

  • Story source must be copy-paste-ready for a consumer integrating the component in their own app — no edits required to run it.
  • Stories must expose the full prop contract: required props, optional props, and event handlers.
  • Validation states and failure modes each get their own story — never document only the happy path.
  • Do not use demo fixture data that would never appear in a real app (no lorem ipsum behind fields with real, meaningful labels).
  • Before creating a story or docs page, search for an existing file with the same or similar sidebar location.
  • When replacing a story, delete the old file before committing the new one. Use a temporary (deprecated) suffix only if both must coexist briefly.
  • Fill every Markdown / MDX table cell — never leave a cell blank. Use - per the global Markdown rules.
  • Run pnpm build-storybook as the duplicate-title check before declaring the work done.

Why

Decorative, partial, or misleading examples are worse than no example: a consumer who copies a story expects working integration code, and an AI consumer reading the same surface inherits any lie in it. Folder-derived placement and complete tables keep the docs build deterministic. This record reconciles ADR-017, which allowed an em dash (—) for “intentionally absent” cells and - for N/A; current dmwd-io practice (the global Markdown hard rules) is a single convention — fill empty cells with - — so the em-dash variant is retired.

Applies when

You are writing a new story, renaming or replacing a story, reviewing a PR’s story additions, auditing existing stories for quality, or creating or editing any table in MDX.

  • ADR-008 — Storybook preview border truthfulness.
  • ADR-019 — Storybook draft state.
  • ADR-016 — Storybook information architecture (root allowlist).
  • ADR-016 — Storybook internal link governance (regenerate the link map after a docs path change).