Diagrams live as text in my markdown files, so they version-control like code. I can see exactly what changed in a PR diff and review architecture the same way I review implementation. No binary files, no merge conflicts I can't resolve. Speed is the other thing. A diagram that took me 30+ minutes in a GUI tool takes under 5 minutes now. I iterate as fast as I can type no dragging boxes, no fighting alignment. It also works well with AI-assisted development: I can generate and refine diagrams programmatically, which isn't possible with click-and-drag tools. I use it daily for multi-agent orchestration flows, data pipelines, and system architecture.

An external integration started causing confusion because we had three different explanations of the same flow. The ticket described one sequence, the documentation still showed an older diagram, and the code already included retry logic that appeared in neither. I opened Mermaid Live Editor, wrote a sequence diagram with our API, the provider, the queue, and the worker, and within a few minutes we were talking about the real behavior instead of spending the meeting dragging connectors around a visual canvas. That’s where Mermaid works best for me. Because the diagram is defined as text, adding another participant, changing the order of a call, or showing an alternative response is usually quicker than editing a traditional diagram. The Live Editor updates the preview as I write, and it lets me share either a view-only link or an editable one so someone else can adjust the diagram and send back a revised version. When the final output needs to look cleaner, we also export SVGs for documentation and presentations. Gantt diagrams are useful for lightweight technical timelines, too. I can show discovery, development, testing, and deployment in the same Markdown file and export the result as SVG, PNG, or a link. I wouldn’t replace a project management tool with it, but it’s enough when the timeline belongs inside a technical proposal or architecture decision rather than a full delivery plan.

I write a lot of user-facing documentation as well as operational runbacks, and Mermaid makes it extremely simple to include graphics, charts, workflow visualizations, etc. I can include the raw code, which makes it easier for others (or Future Me!) to make changes to lt later on. I can use the web interface or IDE extensions (e.g., VSCode). There are also plugins for Confluence, etc. The syntax isn't overly complicated--basically markdown--but as a lazy person, rather than memorize it, I started using third party AI tools (e.g., Gemini) to describe what I wanted in simple narrative descriptions, and let it create the code for me. Later, I found the native AI capabilities within Mermaid itself made this even easier for realtime chart creation within the mermaid.ai interface. The price is minimal and worth it. I really couldn't have created these diagrams on my own - my skills stopped with MS Paint. The support is also top notch - very personable, responsive.