Sooner or later when creating software you end up drawing diagrams to understand and to explain how the system you are building works. The best drawings are those you create on a whiteboard while talking. Here you can communicate a ton of information in short time. You can also use online tools such as Witeboard to have conversations about software design in a video call, less efficient but doable.
However, for design documents and system documentation you want diagrams that are a little bit more polished and that can be read by future generations of developers. I find that Mermaid is a great tool for creating and maintaining such diagrams.
What Mermaid can do for you
Mermaid is a diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. Essentially, you write a specification of what diagram you want, then Mermaid creates the diagram for you.
What is super nice is that you have a textual representation of the diagram that you can embed directly in your wiki. Changes to the diagram are visible in the page history just like textual changes. When the system changes later, editors can update the diagram at the same time when they update the system documentation without installing or licensing additional software.
Another very nice feature of Mermaid is that there is a WordPress plugin for it which just underlines how versatile it is. So it is super easy for me to show you some examples. If I want to go back later and fix an error in this post, I just edit the Mermaid markup directly.
Example: Component View
Component views show a static view of how the components of a system relate. Components can be as small as an instance of a single class or they can abstract away something much more complex.
In Mermaid we can create a simple component view using a flowchart diagram. The syntax
flowchart LR Consumer --> Provider
generates the following diagram:
While some people read arrows as the direction in which data flows, I find it most useful to have arrows represent dependencies. In the above diagram, the Consumer depends on Provider to fulfil its function in the architecture. Hence, even with such a simple diagram, we need a key or legend to explain what the boxes and arrows mean. Never trust a diagram without a legend.
The flowchart diagram syntax allows you to customise the appearance of arrows and boxes and to put labels on arrows. Here is another example that illustrates some of these features.
flowchart TD database[(Database)] client[Web client] server[Web server] client --https--> server subgraph . server --SQL--> database end
Example: Class diagram
I don't often draw class diagrams as these don't communicate much else than what is in the source code. If you need a class diagram, then perhaps your model is too complex. Or maybe it is just me.
Anyway, if you need one, Mermaid has you covered:
classDiagram Creature <|-- Mermaid Creature <|-- Fish Ocean o-- "*" Creature : contains
Example: Sequence Diagram
A much more usable diagram for talking about how a software system works is the sequence diagrams (also known as swim lanes). Sequence diagrams show how different actors or components talk to one another in an example flow.
Mapping out a sequence diagram is a great way to expose misunderstandings and false assumptions. Authentication. Protocols. Identifiers. Logging. Message types. Time outs. Error messages. These are all too often implicitly assumed in a component view while essential to implementing the system. While things quickly get too complicated to flesh out more than a few sample sequence diagrams, these first few will be well worth your time.
With Mermaid sequence diagrams you can create these and discuss and update with stakeholders during a requirements session. Here is a simple example.
sequenceDiagram participant human as Alice participant cat as Cheshire Cat human->>cat: Would you tell me, please, which way I ought to go from here? activate cat cat->>human: That depends a good deal on where you want to get to. deactivate cat human->> cat: I don't much care where. activate cat cat->>human: Then it doesn’t matter which way you go. deactivate cat
When to use Mermaid
Mermaid doesn't make the most beautiful illustrations. That is a strength! Beautiful diagrams are dangerous! People look at them and tend to think: It looks nice, hence it must be correct. In marketing, this is desirable. In engineering, it is dangerous.
A diagram is simplified drawing of something complex. Just like a map. It does not tell you the whole story. It may not even tell you a correct story. As a reader, you need to put in effort to understand the diagram, what it says, and what it does not tell you. A rough illustration that can be easily updated invites you to engage. If you find a mistake, you can correct it. If your change was incorrect, you can roll it back. The diagram becomes an active part of the documentation, just like the text. Engaging with the diagram is a conversation, not like reading mysterious stone tablets from the past.
If you want to sell a product or service, by all means use Power Point. If you want documentation that only your architects can understand and maintain, by all means use Visio. If you are on Confluence and don't mind paying for training and licensing, Gliffy may be for you. If you are on Azure DevOps and need a maintainable diagrams for your system documentation, go for Mermaid.
I'm available for new assignments. The role I'm looking for may be called Technical Project Manager, Tech Lead, Full Stack Developer, or System Architect. I'm looking for a permanent position in the Stockholm area in a product delivery organisation. Get in touch if you need a hands on problem solver with 20 years of experience within software development.