N Noer

D2 solves the stale diagram problem

Noer D2Diagrams as CodeDocumentation

A product-operations view of D2: diagrams as code matter because outdated architecture maps create real delivery risk.

D2 is useful because stale diagrams are an operations problem. When architecture knowledge is trapped in screenshots, teams make decisions from outdated maps.

The maintenance problem

Every platform team has diagrams nobody trusts. They looked good in a meeting, then the system changed. Text-based diagrams make the update path cheaper: edit, diff, review, render.

The best use case

Use D2 for diagrams where correctness matters more than decoration: dependencies, flows, deployment topology, ownership, and failure paths. Those diagrams should be close to the code and reviewed as part of delivery.

Rule of thumb

  • If the diagram is knowledge, store it as text.
  • If the diagram is marketing, use a design tool.
  • If AI generated it, review it like code.
  • If nobody owns it, it will become wrong.

The point is not prettier diagrams. The point is diagrams that survive contact with real engineering change.