- There’s an almost wysiwig editor for mermaid at https://www.mermaidchart.com/play . It’s very convenient and appropriately changes the layout as you draw arrows!
- Notion supports inline mermaid charts in code blocks (with preview!) It’s awesome for putting some architecture diagrams in Eng docs.
There’s also a specific sequence of steps to import mermaid scripts, I don’t remember the menu location by heart, ChatGPT can also give you the steps needed to do this.
I've been starting to include them in my bigger PRs and reviewers really like them.
1. Draw a DAG of whatever pipeline I’m working on with pen and paper.
2. Take a photo of the graph, mistakes and all.
3. Ask ChatGPT to translate the image into mermaid.js
Given how complicated the pipelines are that I’m working with and the sloppiness of the hand drawn image, it’s truly amazing how well this workflow works.
I'm a busy person. I don't have hours of time that I can take out of my schedule to generate what I regard as write only documentation (nobody will ever read or truly value it) that ticks the box of "we have stuff to point at when somebody asks (which nobody ever will)", which has a lowish value. Sometimes it's nice to have. The above is a fine example. People will glance at it, give me a little thumbs up, and then give me permission to proceed as planned and bill accordingly. Job done. It's not a reference design that anyone will ever look at for more than a few seconds.
After a few decades in the industry, I'm extremely skeptical of the value of diagrams vs. the time required to produce them. I just don't see it. A lot of good software gets produced without them. You don't need blueprints for your blueprints, which is what source code is (a blueprint for automatically compiling into working software). People value such traits as structure, readability, conciseness in source code for a reason: it allows them to treat source code as design assets. I don't write UML, I stub out data classes and interfaces instead. And then I refactor them over and over again. Diagrams just slow me down.
But a few minutes is about on the threshold of me wasting braincycles on producing them and enrich documentation that I'm writing anyway in text form. Quickly jot down some notes. Don't waste any time whatsoever obsessing about the awkward syntax of these micro languages, and just get the essentials nailed. I bet I can get it down to like a minute or so with better LLMs and larger context windows. "Examine this project, produce an overview diagram of all the database tables". That's a prompt I'd write. In the same way, letting LLMs document code is a great use of time.
But what's the point of producing such documentation? I could imagine that the process of creating it could be somehow beneficial (committing to memory, finding discrepancies, etc). If it's not, why can't it just be skipped?
Note however that sharing understanding works on the people axis and on the time axis. Docs allow you to share your current understanding with your future self. They’d better be general enough to be true then, though.
Nowadays I find Gemini pro to be able to accurately document a complex workflow within minutes just by looking at the sources and sometimes even just logs, so value of low level docs is questionable. High level requirements - essentially how it’s supposed to work and what for - is very valuable, as it allows you and the model to cross check whether things work as they were intended.
And as you might understand from what I just said, I rarely produce any diagrams. I've been active as a developer since before UML got popular and then peaked and then faded into obscurity. I still have a signed (by Martin Fowler) copy of UML distilled on a shelf somewhere gathering dust. First edition and everything. I don't think it's very valuable. Waste paper basically. But contact me if you feel otherwise. It's in pristine condition because I never did much more than thumb though it and shelve it.
25 years ago, any self respecting architect had expensive licenses for things like rational rose or visio. And they'd be fiddling with those tools for hours to produce detailed class and other diagrams. And those diagrams were as useless then as they are now. Epic waste of time. People stopped buying and using those tools. This was once a very big industry that has now imploded to next to nothing. Nobody is buying, very few people waste budget on this crap. It's a niche market with some niche revenue. Tens of millions of developers ignore these tools.
What do plantuml, mermaid, and other OSS diagramming tools have in common? The people that make them don't eat their own dogfood to document how their own software works. You can have some fun looking for diagrams in OSS projects. With few exceptions, this is not a thing (devops people seem to have a weird obsession with diagramming. And overengineering). I'm not aware of many serious OSS project where developers have bothered to document even a tiny fraction of their software with diagrams. Including all the major OSS UML diagramming tools.
The documentation for these contains plenty of examples of course (typically very simplistic). Just not any that document how the tool is designed or works. I'm not judging. I wouldn't bother either for reasons that I articulated above. But I find it ironic that even diagram tool developers don't seem to feel an urge to use diagrams for their own stuff. Makes you wonder why they bother creating the tool? You'd have to be passionate about diagramming tools but not so that you'd want to use them for your own software.
I draw a fair bit on a Kindle Scribe. I’d love to try this, but I bet your prompt would be helpful.
> I have an image of a hand drawn workflow diagram. I’d like to turn it into a mermaid.js file.
(with the image attached)
We're now experimenting with creating design questions to ask in interviews with excalidraw/mermaid
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [
{
"type": "rectangle",
"version": 175,
"versionNonce": 279344008,
"isDeleted": false,
"id": "2ZYh24ed28FJ0yE-S3YNY",
I end up creating a lot of sequence diagrams and having them as editable mermaid is very convenient. I do wish GitHub giant mermaid navigation controls floating over the bottom right corner obscuring things.
Only downside is AFAIK no in-browser renderer.
> Proprietary layout engine developed by Terrastruct
> TALA is a separate install from D2, to keep a clean cut between 100% free and open-source D2, and proprietary, closed-source TALA.
The two non-proprietary layout engines are 1) Dagre, a port of ideas from Graphviz to Javascript, where the only benefit over Graphviz seems to be "it's in Javascript!" 2) ELK, a fairly naive layout engine that makes non-symmetrical graphs with oddly crooked lines.
I always tend to end up using ELK.
It’s so handy for putting a sequence diagram in your docs and then tracking the changes over time using git.
I’m curious what other software developers use if not this. I’ve tried specific graph and drawing tools like lucid and Visio, but the simplicity of mermaid is nice. And I don’t know anything else that shows git blame for who changed what in my diagram, when.
I like miro for brainstorming and such.
You could do this with any diagrams-as-code tool, no?
I think you are talking about "just change the text and regenerate", which achieves much the same goal.
I'm not sure in what cases the former is better.
I’ve used AI to build mermaid diagrams during ongoing system design discussions from transcripts as they progress.
I’ve rendered them, shared them and then the group can look at them and iterate very quickly.
A bunch of the rendering tools aren’t great, but some are and decent basic styling makes a big difference.
Mapping out database tables while I’m conceptualizing an idea is what I use it more most often. I also use sequence diagrams to map process flow or try e flow of information.
Also, AFAIK, their "render locally" story is "boot up headless chrome, good luck" which isn't great
The "render locally" situation was enough friction to keep me happy with my .jpgs and .pngs generated from various sources and/or screenshotting.
The "in readmes" is a special case because the markdown rendering in both GitHub and GitLab support it without drama
graphviz does okay, but I kinda want some extra levels of grouping to keep services in the same k8s namespace close together.
They can be nested.
https://graphviz.org/Gallery/directed/cluster.html
https://github.com/ReneNyffenegger/about-Graphviz/blob/maste...
It's not exactly what I was hoping for, but is an improvement on the randomization I had going on before!
Fortunately, I don't intend to add arrows into clusters, I just want stuff in the same k8s namespace to be near each other.
When I made it, nothing like mermaid, plantUML，lucid charts existed. The syntax of most tools was based on Java or graphviz and overly verbose. I was writing an email to a colleague at BlackBerry and wrote out the sequence diagrams as text. I spent the next week making a script to convert it to an image and put it online. Many other tools have since adopted the syntax and I'm happy it has become so widespread.
It was indeed pioneering in its day, though I find the default mermaid integration in the likes of Notion make it the (generic) goto for the team now.
WebSequenceDiagrams has been my go to for years, and I'd be basically brainstorming straight in it in lieu of pen and paper. I laughed the day one of my colleague was explaining his issue on the whiteboard and he was writing it "A->B: some action" style instead of the actual box and arrow sequence, it just became part of our culture I think.
I had to move on when I couldn't get it approved at the place I worked, and nowadays PlantUML tools have become "good enough" (still wish Notion had PlantUML support instead of mermaid...), but I'm incredible thankful your service is still up and running.
Note that DrawDB (www.drawdb.app) does this, although it does not yet handle views. But I have been happy with what it offers so far. Still, I would welcome suggestions of other tools.
plug: https://github.com/dgoffredo/sqliteviz
Not web based, though.
Not the prettiest, but workable.
I wouldn't try it on 100 tables.
Disclaimer: I work for them. I’m the person who developed that feature.
Feedback welcome!
