Comment by 5Qn8mNbc2FNCiVV 2 days ago
Never seen a bigger waste of time than when my colleague (who was given more authority for some reason) tried establishing Mermaid as our go-to diagramming tool for the company.
Had no real benefits, was way more cumbersome for almost everyone and honestly even me as a developer I'd rather have a few paragraphs instead of a diagram.
Somehow it's just never "readable"
I use excalidraw, even upgraded to pro out of my own pocket. It's not git-compatible in the sense that it's not text (though you can export to SVG and commit that, which I've done). But I love that it has the feel of an approximation or just a quick sketch rather than a formal promise of how a system works.
When I've used dot or mermaid to build diagrams I've always found it hard to specify layout, colours and sizes, which I use to emphasise different views on a system. I'd love some sort of middle ground where I get the benefits of version control but also the sketch-like character of excalidraw
Nowadays I use mermaid, but I only use sequence diagrams. They're incredibly useful to convey to a client at a high-level what are the different workflows in a system.
Had no benefits/was more cumbersome than what?
My colleagues frequently use one of these general-purpose WYSIWYG drawing tools, and I'm not a fan at all – everybody has their own slightly or wildly varying riff on UML or flowcharts, and the result is chaos: Sometimes rectangles are states, sometimes they're decisions; sometimes arrows are labeled state transitions, but other times they're unlabeled and state transitions are also boxes.
Discoverability is also much worse compared to e.g. Mermaid or PlantUML diagrams checked into version control or stored as text source in Wiki articles.
I also ran into massive issues trying to use Mermaid when I tried to pair it up with Marp (markdown for presentations). I am not sure if it is Mermaid's fault or Marp's fault but it didn't work and tons of people want it to work:
The discussion seems to make it pretty clear where the issues are, though, and how you can get around them using mermaid's render to svg.
I'm curious what you prefer instead?
I find that tools like Mermaid are pretty invaluable, especially when editing very large processes. Draw.io diagrams tend to get pretty unwieldy as they scale and editing inter process stuff if you forgot something quite frustrating.
Sequence diagrams are possibly my favorite feature in Mermaid: https://jessems.com/posts/2023-07-22-the-unreasonable-effect...
Admittedly I primarily use D2 nowadays. The only features I miss in D2 from mermaid are the GitHub automatic rendering and Sequence diagram numbers. https://play.d2lang.com