3 ms·
I use this not infrequently when producing documentation. But it's one of those things which is most of the time ok, but when it's not it's very dissatisfying,
by abeppu 6y ago
I use this not infrequently when producing documentation.
But it's one of those things which is most of the time ok, but when it's not it's very dissatisfying, and I don't have a concise term for the (common) source of that dissatisfaction. When it produces a poor layout, you have to either abandon the tool completely for that use case, or you have to use an entirely different tool set to fix the output (like just editing the SVG).
I think this is a bit challenging, because if you're hand-writing the structure describing the diagram, you likely have some preconception of what it should look like, but the language doesn't give you a real mechanism to express that. And because the diagram is meant to be _looked_ at, the author's preconceptions may actually be quite relevant in how effective the diagram is at communicating content to a later reader. This is in contrast to a compiler, where the author may disagree with the specifics of the output, but so long as it _runs_ to produce correct behavior, the author should not complain too much (i.e. the primary "audience" is the platform which will execute the program).
As an example, only this past weekend, I tried to produce a diagram about an HMM-style graphical model, where nodes occur in sequence in a few parallel families. I had hoped that because of the regular structure of the links, the layout would reflect that regularity. But instead, nodes of each type were sort of all over the place, and the regular structure was actually not immediately visible in the diagram.
- kevsim 6y agoI've been considering integrating the ability to embed diagrams written with Mermaid into the issue tracker I'm building [0]. Would you say it's ready/robust enough for that? People typically want to scribble down quick architecture or sequence diagrams (or maybe some class diagrams). 0: https://kitemaker.co https://kitemaker.co
- gnabgib 6y agoI really like Mermaid, and use it quite a bit (people forget how long they spend dragging boxes, arrows, aligning in Visio/DrawIo), but for some diagram types, you have no control over layout, there isn't even hinting (yet - it continues to improve). Sequence diagrams are great. I imagine Gantt charts are fine. Flowcharts will sometimes be rendered unintelligibly.. adding/removing a link or new element will completely rearrange the layout. If you have any implied order of your flow (as simple examples on the website imply) this maybe rearranged as your flow gets more complicated. If you want flowcharts over swim lanes (either distinct or implied - think of data-processing ingress on an app), or the start point first and the end point last - this isn't a great tool. There is support for subgraphs, but you have no control over their location either.. so if you want a web-firewall-loadbalancer-app-db type flowchart, it may be rendered in a circle.
- blahblah12 6y ago100% this. Mermaid is fantastic for the happy path, but as soon as you run into any issues, the lack of flexibility makes it nearly impossible to use (It tames more time to use mermaid than to go back to traditional diagramming tools).
- TeMPOraL 6y ago> I don't have a concise term for the (common) source of that dissatisfaction Declarativeness + fragility. That's how I refer to similar experience with PlantUML. Everything is fine, but then if you as much as look at it the wrong way, the diagram gets twisted inside out. It's manageable once you get some experience with it, but I really miss the ability to inject some additional hard constraints into the diagram, like "I don't care what your layout engine thinks, these five nodes are to be in top-left corner and should line up perfectly; arrange everything else around it". I'd happily take 5-10x longer image generation if that's what it takes to have a proper constraint solver involved. Regardless, it still beats the hell out of arranging diagrams with a mouse. With PlantUML in particular, once you learn how to use the preprocessor to define macros, building larger diagrams becomes super-fast.