Why create diagrams?

I don't do a lot of diagramming, but occasionally it can be a valuable tool. Diagrams can help us understand a situation in new ways. Words alone may not be sufficient, especially if the people who are trying to communicate come from different backgrounds or don't share a native language. Diagramming can be a fast and powerful way to communicate. The diagram can be a tool for thinking, individually or as a group. It can be more than just a way of creating documentation. It doesn't always need to be 100% correct when it is used as a tool for generating new insights. If you don't diagram already, try it out!

Where I am coming from on this topic

Some people may have learned to make diagrams while they were studying. A lot of people who program or design systems did not study computer science and may not be familiar with the practice. The same is true for myself.

Over the years I became accustomed to reading diagrams. Some people I worked with were old-school computer scientists who used a specific notation (UML) that took some time getting used to, especially as it wasn't really explained to me, and I did not have reference material. Occasionally I was tasked with creating class diagrams in specific UML tools, but personally I don't find creating hand-made class diagrams useful because they become outdated. When I was thinking about a new system or trying to find the source of bugs in a complex interaction I would doodle a bit on paper, but I was not comfortable sharing these drawings because I did not like the idea that people would think I didn't do them 'right'. Due to all this I quickly forgot about diagramming when I moved on to other assignments.

Today, I don't want 'right' to get in the way of 'useful'. I don't think we need to go all-in with the Unified Modelling Language (UML) to enjoy the benefits of the occasional quick diagram.

What does a diagram look like?

The official PlantUML site and Real World PlantUML have good examples that might get you inspired, and show the basic building blocks. A specific page I want to share is the deployment diagrams overview on uml-diagrams.org . I think it is a good demonstration of how a lot of useful information can be expressed in a diagram.

Of course there are also different situations where you might diagram, such as describing use cases .

My own PlantUML notes page shows the source of this example diagram.

Personally I don't bother too much with the 'correct' ways to draw something. As long as the general idea is clear the diagram can be of value. I do think that it will benefit the usefulness of your diagrams if you look up the basic conventions for the type of diagram you want to make. For example, there is a specific way to draw the connection between an interface and an implementation . It needs to be clear which element is the interface, which elements are using the interface and which elements are implementing the interface. It is good to use notation that people may already be familiar with and can be understood in the future, when we have moved on.

Pick any tool to start

I like the PlantUML tool. I use it as a command on the commandline, and write the diagram in whichever plain text editor is at hand. They also provide an online service . I think PlanUML is a low-complexity way to go. Unfortunately error messages can be short and unclear. The example pages I linked to earlier can be handy to see how types of diagrams can be made.

Personally I feel that pencil and paper or any drawing program can be a valid tool for diagramming. Especially when we just want to get the basic ideas on paper, in a way that can be used as a starting point for further thinking.

If we are using software it can be handy if we also have a drawing program with support for multiple layers. Then we can add notes on top in a different color, like we might do with pencil and paper during a conversation with our colleagues. The multiple layers then make it possible to switch layers of notes on and off.

Pick any tool from a search result. Try out several if you like.

Automatic class diagrams

Sometimes we want to have class diagrams for existing codebases. Luckily many integrated development environments support creating them automatically. I have done so in the past with Microsoft's IDEs. IntelliJ IDEA also seems to support automatic class diagrams.

Conclusion

Diagramming can be a great way to jot down your thoughts, and offload whichever system design you are thinking about to paper, or computer. It allows us to think about the system in new ways. This is difficult to explain in words, and best experienced by yourself. If you don't see the use yet, just keep it in mind for the next time you need to communicate your ideas, or analyze a system.