Diagram as Code

Original Article ↗ Hacker News Discussion ↗

Overall Reaction

  • Many find the idea and execution appealing, especially for people already using Python and doing infrastructure-as-code.
  • Others see it as clever but not the right solution for everyday diagramming, especially when non‑developers are involved.

Using Python / DSL vs Dedicated Languages

  • Debate over using a general-purpose language for what is essentially a static structure.
  • Supporters: embedded DSL in Python gives IDE support, reuse of ecosystem, and fits teams already coding infra.
  • Critics: overkill vs simple DSLs (Mermaid, DOT, YAML/JSON); raises barrier for non‑Python users; diagrams are not “programs.”
  • Some dislike the context-manager API as opaque “magic”; others see it as a concise way to manage shared state.

Accessibility and Output Formats

  • PNG output is criticized as inaccessible to screen readers.
  • Some suggest text descriptions, ASCII diagrams, or more accessible vector/semantic formats, but no clear consensus on best format.

Comparisons to Other Tools

  • Mermaid, PlantUML, D2, Graphviz, DBML, draw.io, Excalidraw, and others are frequently cited.
  • Mermaid and PlantUML praised for integration with GitHub/GitLab and AI helpers.
  • D2 praised for its layout engine and animations.
  • Visual tools (draw.io, Excalidraw, Lucid, OmniGraffle) preferred for collaboration, presentation, and “nudging” elements.

Diagram Layout, Scale, and UX

  • Layout engines work well for small diagrams but often degrade on larger, complex ones (overlaps, odd ordering, broken directions).
  • Many find designing diagrams entirely in code frustrating; they want a visual editor and code export, or at least rule-based layout tuning.

Version Control, Collaboration, and Publishing

  • Strong desire to keep diagrams under version control, but text diffs on diagram source or SVG/PNG are rarely meaningful.
  • Some workflows embed diagrams in wikis or Confluence via plugins or custom pipelines; others accept that rich diagrams live in the corporate wiki outside strict code workflows.

“Diagram as Code” Semantics and Expectations

  • Some argue this tool is “code to diagram,” not “diagram as code,” and expect “diagram as code” to imply infrastructure/code generation from diagrams.
  • Others use “X as Y” more loosely (representation rather than direction of generation), so terminology remains contested.