I’ve recently started ditching Lucidchart diagrams in favor of Mermaid, and its companion live editor. I’m really enjoying it! It’s just another step in my gradual return to text, though I suppose there is a bigger story there.

The switch from Lucidchart (or Miro, if you prefer) to Mermaid should feel familiar to anyone who has vacillated between GUIs and CLIs. The former is more intuitive and fun, while the latter is more powerful and composable. Text is a simple but powerful modality!

The first thing I notice with Mermaid is that I lose the ability to do freehand layouts - some controls are available, but Lucidchart is by far more flexible and intuitive for fine-grained layout control. Instead, I keep myself to identifying the nodes and edges of a graph, and Mermaid determines the layout. That is a weakness but also a blessing - I find sequence diagrams to be a royal pain in the neck to layout freehand, but they are absolutely trivial in text. On the other hand, if I need to depict a complex information flow across a suite of microservices, and it’s important to highlight patterns and anomalies, then careful layout is crucial. So I’m unlikely to drop Lucidchart altogether, but Mermaid fits the bill for a wide variety of simpler use cases.

What I really enjoy about Mermaid is that it integrates really nicely into my document-writing process. I can flip back and forth between prose narration and diagram edits without shifting context or opening a different app. In particular I find myself using Confluence’s /mermaid command, which renders a block of Mermaid code embedded directly into the document. The mechanism is a little clunky - I tend to hide the Mermaid code in a /expand block to focus the reader on the graphics - but the results are really nice. With Lucidchart I unwittingly fell into a kind of waterfall process, whereby I’d write a bunch of text for a while, and when I’m done with that I turn to diagram layout. With Mermaid I find that the text and diagram remain in active conversation with each other, that tweaks in the text readily become tweaks in the diagram and vice versa. It’s a much cleaner way to think, and produces more up-to-date diagrams in the bargain. The cherry on top is that your diagram gets versioned alongside your text, with Confluence’s versioning tools, which satisfies my inner code historian. Again, none of these revelations are new to anyone who’s juggled GUIs and CLIs before - for example scientists who need to shift between LaTeX and data manipulation will likely see similar results - but it certainly is gratifying.

Key to this entire transformation is the advent of text-based LLMs, which have helped me to narrow the gap between text and diagram substantially. I began this whole adventure by asking ChatGPT to turn a block of text describing an information flow into a Mermaid chart. The process needed some tweaks - at least at the outset I found that ChatGPT did not properly identify the “actors” who formed the nodes of the graph, and I had to coach it. But once I got the hang of it, I quite enjoyed the ability to more-or-less automatically traverse the bridge between prose and diagram in both directions. Sometimes I draft Mermaid code by hand, especially if the diagram in question is pretty simple, but the “automagical” tool is quite handy to have all the same.

It’s not lost on me that LLMs are kicking off a Renaissance for text-based tooling. I am here for it!

There is a larger story to be told, about the document generation and versioning process writ large. I am still using Confluence as the archive of record for documents, and that means I rely on Confluence version control, and that’s fine for now. But it’s an awkward fit with a more agentic workflow, in which an agent powered by a heavy-duty thinking model can take on the task of structuring a document, dig for the information to power key decisions, and revise a document according to those decisions. Recently I was working on a document, and as I was putting the finishing touches on it I realized that the system I was describing would be far simpler if I changed the eventing pattern from event-notification to event-carried-state-transfer. That in turn required digging up some more details, figuring out which pieces of the document needed to change, revising narration, tweaking the diagram, and so forth. Some day, and I think it’ll be soon, I’d like to change my workflow so that I can just prompt Opus with something like “we need to shift this approach to event-carried-state-transfer, please figure it out and make the necessary changes.” Then I could go grab some coffee and enjoy my higher layer of abstraction.

I suspect that tools which automate this kind of design work are not very far off! In the meantime, if you haven’t had a chance to play with Mermaid, I highly recommend it.