26 August 2023
In this article, I’m comparing four different tools for creating diagrams. If you want to skip straight to my recommendations, jump to the conclusion; otherwise read on for some explanation of what I was looking for and how I did the comparison.
As a programmer I find myself using diagrams to explain or document things pretty regularly. Every time I do so, I wonder which tool I should use to create the diagram -- there’s a lot of options, from generic drawing tools like Inkscape to very specialized ones like mscgen, which creates “message sequence charts”. A few days ago I was about to create a diagram for a proposed change to the system I’m working on and I decided to use the opportunity to compare the most promising tools.
I started out with four criteria for diagram software: (1) it should make it easy to create a diagram with boxes and arrows (2) it should be open-source (3) I want the resulting diagram to look good (4) ideally, the diagram should be specified as code so I can use version control and see a meaningful diff between versions. Realistically, creating a diagram with code is going to be harder, so I expect either (1) or (4) to be met.
I tested four pieces of software: draw.io, Excalidraw, Mermaid, and Pikchr. The former two are web-based GUI software that also offers a downloadable version; the latter two are text-based but also have a live web version that makes it easy to try them out. All of them are open-source.
To have a meaningful comparison, I tried to create the same diagram in all four, based on this sketch:
This is the actual diagram I need for work, with names replaced by nonsense words. It shows the services making up part of our backend; the stacked boxes on the left side are meant so indicate that we’ll eventually have multiple similar services there, all exposing the same interface. The poorly-drawn cylinders represent databases.
I made a second version where some of the arrows are annotated with the protocol used:
My idea was to create both versions in each diagramming tool. I ended up also creating a third version using colors instead of labels because I didn‘t like how cluttered some of the labelled diagrams looked.
To help judge the ease-of-use of the tools I timed how long it took me to create the diagram in each. Don’t read too much into these numbers -- this isn’t a scientific study -- but they can give a rough indication. Otherwise, I made notes on my subjective experience with each tool and compared the results to see if they looked the way I wanted them to. I’ve included one diagram for each tool below, with links to the other two.
draw.io was, in every respect, good but not great. Its UI is pretty easy to use, but I found it a bit fiddly -- for example, there were several times when I’d click and drag to try to resize an object, and it would draw an arrow starting at that object instead, or the other way around.
Here’s the diagram without labels or colors:
I quite like this one, actually, but I don’t think the other two look as good. You can see them here: draw.io diagrams. It took me 27 minutes to create and export all three.
Excalidraw worked really well for me. It’s going for a hand-drawn sketch look:
Its UI is really simple and was a joy to use. I was faster than with draw.io (20 minutes) even though I had to manually create the stacked boxes and the cylinders because Excalidraw’s simpler data model doesn’t support these.
I suspect the hand-drawn look won’t be everyone’s cup of tea, but I really like it. It suggests that the diagram isn’t necessarily authoritative -- it’s one person’s view, at one point in time -- which is true for most diagrams I make.
You can see the others here: Excalidraw diagrams. I don’t love how the labels cut into the arrows in the labelled one, but I think the colors work better here than with draw.io.
Mermaid just turned out to be the wrong tool for the job. Before we get to that, one positive point: it only took me 22 minutes to create the three diagrams using the live editor and online documentation -- less than with the GUI-based draw.io!
However, the result wasn’t what I wanted at all. Look at this monstrosity:
The others are here: Mermaid diagrams. The problem is that Mermaid doesn’t just let you create “a diagram”; you have to pick a diagram type such as class or sequence diagram, define the elements of the diagram, and then let Mermaid determine the layout. I went with the Flowchart diagram type and defined the services and databases in the diagram as nodes in the flowchart.
At this point you might object that this isn’t a fair comparison: I’m abusing the Flowchart diagram type to do something it wasn’t intended for. That’s true, but using it like this seems to be pretty common. Since GitHub added Mermaid to its support for Markdown documents, I see people treating Mermaid as the default solution for creating diagrams, and the results are not great.
Pikchr is pretty impressive, but probably not what I need at the moment. Its output is excellent:
That looks really professional! Even the labels on the diagrams look good. You can see the other diagrams here: Pikchr diagrams.
Pikchr was created by the author of SQLite and it’s used to good effect in the SQLite documentation (example). It uses a clean line-based syntax that I think would work nicely with version control and text-based diffs.
The downside is that you do have to invest some time. It took me 1 hour 16 minutes to create the three diagrams, and although I’m sure I’d get faster with practice, I don’t think writing Pikchr code will ever be as quick as using the Excalidraw UI.
Which tool is the best for the programmer looking to create some diagrams? I have two recommendations, to fit different circumstances.
My default recommendation is Excalidraw. It’s easy to use, the results look good, and the hand-drawn look is suitable for most diagrams.
I’d use Pikchr for diagrams that are intended for a wide audience (so I’d want them to look professional) or ones that I know will be maintained over a long time (so the text-based format is ideal).