When I’m working on a problem I often scribble bits of information on a piece of paper; keywords, questions and parts of software diagrams. These scribbles are part of the process of understanding the problem and finding a solution. Too often these diagrams end up being documentation for the software system: photos of whiteboards taken with a mobile phone. A few days later even the authors themselves don’t understand the scribbles anymore. Knowledge lost.

Obviously there’s a better way to do it.

Ask questions first

That’s why, when I intent to produce a diagram which should survive longer than just that day, I work by three simple rules:

1. Who is the reader?

Who do you want to understand the diagram? The type of diagram and what information you include/exclude largely depends on who is the reader. What understanding (of the system) does the reader already have? Also, don’t forget yourself: I often draw a diagram to guide my thinking process. In this case the reader isn’t necessarily a colleague but just me. Still, check with your colleagues whether they find your diagram useful too, so you can share it with them.

2. What do you want to communicate?

What do you want the reader to learn? Everything on the diagram should be there for that purpose. Add too much (unrelated) boxes and arrows, and your diagram will be confusing. Think of what details matter and which don’t.

3. What notation does the reader understand?

When you know who the reader will be, decide on a form and notation. While most diagrams are just boxes and arrows, it helps to use a standard because it eliminates ambiguous meaning of shapes. Most will recognize a cylinder as a data store, but what about one lying horizontally? Probably a pipe or queue. Hexagon, diamonds, boxes with rounded corners? We can guess (it’s probably some kind of UML diagram) but discussion about semantics are distracting.

C4 Model

I tend to use simple but (more or less) standardized notations, since I don’t have a complete in-depth understanding of systems like UML or ArchiMate and that means people reading my diagrams haven’t, either (except the occasional architect). Since ~5 years I’m using Simon Brown’s excellent C4 model since it can be explained in 5 minutes, is well suited for documented microservice architectures and can be drawn using any drawing/diagramming tool, including whiteboards.

Final note

There is a place for more elaborate diagramming systems as UML or ArchiMate, simply because they provide diagrams that you don’t find in simpler (diagramming) systems. Use them when you need to but make sure your reader knows how to read it:

(Do you know the meaning of each of these symbols and shapes?)