The fallacy of choosing syntax over models in AI diagramming

LLMs invent syntax for sparse notations

Models write mainstream languages like Python or SQL reliably because these languages appear millions of times in training corpora. Syntactic competence is a function of training-data-frequency. When a model encounters an unfamiliar notation, it interpolates syntax rather than failing by using syntax from Mermaid or PlantUML to create something that merely resembles the intended notation. This process yields fluent, well-indented, but incorrect output. A model produces a ten-class diagram with one invented relationship keyword. The parser skips that line, and the resulting design document misses exactly one association. Retrieval-augmented generation grounds facts in a response but does nothing for the notation. A model with accurate knowledge still emits a syntactically invented domain-specific language statement. In a fifty-task benchmark with Claude Sonnet 5, Typed Domain Grounding reached higher Structural Fidelity than two lenient external DSLs. This method anchors the notation in what the model already knows to write. LLM hallucination on a domain-specific language is a training-data-frequency problem, not a knowledge problem.

Mermaid provides speed while PlantUML provides capability

Mermaid reduces adoption friction because GitHub renders it natively in Markdown files. The Mermaid Studio 2026.3.1 release adds Cynefin and Railroad beta types to the runtime. This update also introduces an appearance system with automatic detection of the diagram theme and background. The 11.16.0 runtime allows ER diagrams to accept nullable attribute types like string? and XY charts to accept per-data-point text labels. Mermaid Studio rearchitects onto IntelliJ’s modular split mode architecture to support remote development environments. Knut Sveidqvist created Mermaid because he lost a Microsoft Visio file. PlantUML provides a deeper toolbox for teams needing formal structure or complex C4 modeling. The PlantUML ecosystem includes a well-known C4 library that many architecture teams use for structural definitions. PlantUML has existed since 2009 and remains the standard for UML diagrams in enterprise environments. PlantUML requires a Java runtime or a server-side renderer like Kroki, while Mermaid runs as a JavaScript library in the browser. Most teams use Mermaid for code repos and Draw.io for architecture presentations. Mermaid wins the first week of adoption, but PlantUML remains the specialist choice for deep architectural notation.

Layout constraints and the documentation divide

Draw.io provides pixel-perfect layouts via a drag-and-drop interface. Mermaid relies on an automatic engine to decide node positioning. For teams working in Git, Draw.io produces unreadable XML diffs that fail the requirements of version control. Mermaid layout quality degrades once you exceed fifteen nodes because edge crossings and label collisions occur. You should consider if your team needs to version control diagrams in Git or present them to stakeholders in a slide deck. Mermaid’s syntax is concise, and a simple flowchart takes three to five lines of text. Most teams use Mermaid for simplicity and PlantUML for capability. PlantUML is better for teams that want more control over structure and styling. The Python package Diagrams as Code uses operator overloading to handle complex architecture, but it remains limited to Python users. Mermaid provides high speed for developers who type syntax for instant rendering. D2 uses multiple layout engines like ELK and TALA to improve readability. Graphviz remains the standard for visualizing dependency graphs. Mermaid remains the most widely adopted diagram-as-code tool, but its layout control is minimal. Will the move toward AI-driven syntax ever eliminate the need for a shared architecture model?