Diagram as Code

Original Article ↗ Hacker News Discussion ↗

Turning infrastructure and architecture diagrams into Python code appeals to developers who want version control, reuse and integration with existing tooling, but others argue that using a general-purpose language and PNG output adds unnecessary complexity and hurts accessibility. Commenters compare this “diagrams as code” approach to alternatives like Mermaid, PlantUML, D2, Graphviz, Excalidraw and draw.io, weighing trade-offs between text-based DSLs and visual editors, automatic layout quality, and ease of collaboration with non-programmers. There is also interest in richer features—such as better layout rules, interactive or animated views, and even generating diagrams from natural language or using diagrams to generate infrastructure code.

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.