"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.
No guidance
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.
Content and presentation is mixed
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.
No model, no consistency
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.
Hard to diff
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.
Limited automation
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.
Time consuming
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.
Summary
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!
Top comments (6)
In my opinion, excalidraw.com is all I need as a software architect to create diagrams.
However, I'm not a full-time software architect at a big corporation where my output is measured in how many diagrams I produce and how well I maintain them.
I create diagrams to illustrate the big picture to other team members, partners and other system owners I integrate with. No need for automation, no need for rules and guidelines of what I can and cannot add to my diagram.
Depending on the situation, the requirements, and many other factors, one tool fits better than another.
Making claims such as in the title of this article seems not very helpful.
Point taken, and I will use general purpose diagramming tools when I need to draw something more general. I do genuinely believe that we need to evolve as an industry though. It's 2020, and we're software engineers ... we can do better than using tools that don't understand the semantics of what we're trying to do.
I am working on a tool specific to software architecture diagrams called SystemDraw. Still early days, but you can configure nodes with attributes. You can configure a load balancer with round robin and configure a cache with eviction policy etc.
Although all these points are valid, I wonder if the idea of UML Modes has some impact on this. Diagramming tools are more useful for sketches and notes that have a limited lifespan - they are used and then either discarded or relegated as notes of the discussion rather than continued documentation of the system. Modeling tools are more appropriate as blueprints or some other form of long-lived documentation.
I see tools like Visio and draw.io / diagrams.net as being digital equivalent to whiteboarding. But whiteboarding has its place, but it's a different place than modeling. The question to ask is if you are making a model of your system or creating a diagram of your system. The answer will drive what tools are best suited to the problem.
There are certainly different uses for software architecture diagrams, yes. If I'm doing an up front design exercise, I'll tend to use a whiteboard or flip chart paper. This allows me to focus on sketching out ideas, and it's much easier to do collaborative design with a larger physical space. I'd still use the C4 model (in terms of the abstractions and hierarchical diagrams), but I might not necessarily follow all of the notation guidance. These diagrams tend to form a starting point, and they are usually short-lived. Once we start coding, and I want to start creating long-lived documentation, I'll switch to a tool. Another use case for a tool is for proposal/pre-sales purposes, where you want to show some software architecture diagrams to accompany a "this is our plan" type presentation. Those diagrams tend to be quite short-lived too.
Ignoring up front design (where I still think a whiteboard is the best option), I think we can do better as software engineers, and I don't think we should be using general purpose diagramming tools at all for the creation of software architecture diagrams ... short or long-lived. "Modelling" has some unfortunate associations with heavyweight design processes, but I believe that we can change that with better tooling, as I illustrated in Modelling software architecture with PlantUML, for example. My goal is to help teams create better looking, and more consistent, software architecture diagrams more quickly than they can with a general purpose diagramming tool.
After spending my whole afternoon dealing with draw.io and Microsoft word , just come across this blog post , thank you for sharing plantUML. I really appreciate how easy it is . Thanks you.