Back to Plate

Milkdown tests beat docs for behavior

docs/research/decisions/milkdown-tests-beat-docs-for-behavior.md

53.0.5467 B
Original Source

Milkdown tests beat docs for behavior

Question

When Milkdown docs and tests both exist, which should carry more weight for behavior work?

Decision

Tests win for behavior. Docs win for ownership and API mapping.

Why

Milkdown splits truth across many lanes.

The executable lanes are:

  • e2e input
  • e2e shortcut
  • e2e transform
  • package-local unit tests

Those are stronger than README or docs/api pages when the question is "what does it really do?"