"Which diagramming tool should we use?" is a question I'm asked frequently. Software architecture diagrams - which tool should we use? looks at how to generate software architecture diagrams with PlantUML, Mermaid, WebSequenceDiagrams, and Structurizr, all via the tooling agnostic, and open source, Structurizr DSL. It's "diagrams as text".
But you might be wondering, what about general purpose diagramming tools; such as Visio, draw.io/diagrams.net, LucidChart, Gliffy, OmniGraffle, etc? Should they be used for creating software architecture diagrams? For the record, I want to say that these are all great tools and, like many other people, I do use them myself. For software architecture diagrams though, my recommendation is no, for a few reasons.
The domain specific language of general purpose diagramming tools is basically "boxes and lines". Open up a diagram file in a text editor, and you'll see what I mean. Because these tools don't know that you're trying to create a software architecture diagram, they can't really help you do that. Some people really like the freedom that general purpose diagramming tools give you, but this freedom is exactly what gets most people into trouble. You've opened up an empty diagram. Now what? The tool can't guide you towards creating a good software architecture diagram, because it doesn't know that's what you're trying to do.
UML, ArchiMate, and the C4 model all have rules about what you can and can't do. For example, the C4 model says, "don't put components on a container diagram". But a general purpose diagramming tool can't enforce this, because it doesn't know what a "container" or "component" is. This makes it very easy to mix multiple levels of detail in the same diagram, leading to something that often makes little sense.
Remember the early days of the web, where we'd craft huge HTML files containing all of the information about content and presentation? The same is true of general purpose diagramming tools. Again, open up a diagram file in a text editor, and you'll see this for yourself.
This lack of separation makes it very hard to create multiple versions of the same content for different purposes. For example, perhaps you'd like three versions of a System Context diagram:
- A version with technical detail, for developers and architects.
- A version without technical information, for non-technical people.
- A version with larger fonts and less text, for presentations.
The only way to do this with a general purpose diagramming tool is to copy-paste the original diagram multiple times, and make edits to those copies. But that leads you to the next problem.
Modelling software architecture with PlantUML covers this problem. You violate the DRY principle every time that you copy-paste an element or relationship to use on another diagram. Once you have the same item on multiple diagrams, you need to manually make sure that you keep all copies in sync when you change the content or presentation of that item.
This happens because there's no concept of a "model" in general purpose diagramming tools. You can't easily share items between diagrams. Again, we're limited by the domain specific language of diagramming tools being "boxes and lines". These tools don't really understand that two boxes on two diagrams represent the same thing from a conceptual point of view.
Unless you're using a really old version of Visio that uses a proprietary binary file format, modern diagramming tools tend to save diagrams as text, which is much easier to version control. But diff'ing those files isn't easy. Once again, because the domain specific language of such tools is "boxes and lines", that's exactly what you'll see when you try to diff two versions of a file.
Except it's not that straightforward, because the file formats tend to be very verbose, and they mix content and presentation.
Although it's certainly possible to automatically generate diagrams from other sources (e.g. Visio from Excel, draw.io from CSV), these features are relatively limited. I don't think many people know such features exist anyway - most people I see using these tools are manually creating boxes and lines via the UI.
This is the one everybody will nod their head to! Creating good looking diagrams in general purpose diagramming tools is very time consuming. Templates do help with this to a degree, but they're usually only a starting point, and you often end up with diagrams like this when you start to add more text than can fit in the box.
Now what do you do? Do you just make that one box larger? Or do you resize all boxes to make them the same size? But that messes with your alignment, so now you need to fix that too. After doing all that, you realise you made a typo inside a box, which you fix, but that breaks the line wrapping, and you're back to square one. 🤷♂️
On the plus side, a huge benefit of general purpose diagramming tools is that you do have control over where elements are placed on the diagram canvas. I value this feature, because I'm not a huge fan of automatic layout algorithms and the diagrams they create. Most modelling tools, including the Structurizr web-based renderer, provide the option to manually layout elements, so this shouldn't be the sole reason to choose a general purpose diagramming tool.
I don't recommend using a general purpose diagramming tool for creating software architecture diagrams. Creating models and diagrams as code or text are much better approaches, resolving all of the problems listed above.
Architects and engineers in the building industry use domain specific tooling such as AutoCAD. As software engineers, we can do better too!