[oaiey]

I just posted parallel to your post. What is your positioning of mermaid (and friends like plantuml) vs. visually crafted diagrams?

Textual editing, auto-layouting, little work, obviously, but where is the niche compared to visual editors. As an architect, I have challenges using mermaid when communicating to stakeholders.

[sidharthv]

I feel both have their niche carved out.

For developers, text-based editors are an excellent tool to represent not-so-complex logic/procedures where they don't need to spend time worrying about the visual angle. It's easier to integrate into documentation with a ```mermaid, and easy to keep updated.

So there is no context switching involved in opening up a visual editing tool, downloading the image, integrating it to the docs, then having to repeat the whole process again when there are changes.

As an architect, one of your primary responsibilities would be to create high-level diagrams that need to convey a lot more information to the stakeholders, where the weightage of the visual component is high (layout, colors, etc). Which is where Visual editors shine.

Text - Simple, Quick & Dirty diagrams.

Visual - Detailed, well thought out diagrams.

[weinzierl]

For me it's the exact opposite:

Text - Detailed, well thought out diagrams.

Visual - Simple, Quick & Dirty diagrams.

The reason is mostly that diagrams from visual editors are basically unmaintainable and therefore are only good for throw-away stuff. Also simple diagrams, especially when you are not entirely sure what you want, are quicker done in a visual editor.

If I need to document a complex system and especially when the documentation has to evolve with the system it is generated diagrams from version controlled text files for me hands down.

[Veuxdo]

Very much agree with this. In fact wrote something on this last year almost to the day: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

[oaiey]

Thanks. That is exactly my train of thought on this. Nice to see this positioned also from you.

[sidharthv]

Themes and colors, we can do. I've seen people drawing some spectacular diagrams with Mermaid.

But we cannot easily add layout logic without sacrificing the simplicity of the syntax.

[mooreds]

I think the sweet spot of text based diagram generators is when the intent is high levels of information delivery at low levels of effort. It is super easy for me to say "a sequence diagram would help convey this concept better" and write up a diagram. Whereas if I had to use a visual tool, it'd be a higher level of effort.

Text based diagrams are also easy to:

* version control

* get feedback on (it's a PR away)

* change

Even though you can style the text based diagrams (see this for plantuml styling: https://plantuml.com/style-evolution ) for a cohesive look and feel, visual based editors are still going to win out. I use them for free form diagrams and also presentations.

[knsv]

Good summary @moonreds, I fully agree.

For the styling we can't really compete with the visual tools. In Mermaid we have lots of things we can do in that area to make it better though. Both improving the default styling and handling some common use-cases. We could for instance simplify the highlighting of one specific node in a flowchart/class diagram. You can do it right now ofc but you have to make the style/class yourself.

One should be also be aware though that there is a time trap using styling in the visual tools. I spent lots of time making fiddling with styling of boxes in Visio. :)

--- Creator of Mermaid and founder of Mermaid Chart