Improve Your Technical Diagrams

Contributed by Charles Humble

Difficulty level: Easy

As someone who makes a living largely as a writer, I feel that “natural” language (that has been developed for people rather than for computers) is a maddeningly ambiguous means of communication. Conversely, the code we write as programmers is extremely detailed and precise. Used well, diagrams provide a helpful middle ground where you gain greater clarity than you can achieve from natural language alone, and you can focus on the important points without getting bogged down in minutiae.

Simon Brown, software architecture consultant and creator of the C4 model, has noted that, unfortunately, “Many software development teams have lost the ability to communicate visually.” Brown thinks this may be a side effect of the race to agility. I suspect the difficulty of keeping diagrams up to date, particularly with rapidly changing microservices systems, has compounded the problem.

Whatever the reason, we end up with diagrams that have a mixture of colors and shapes for no discernible reason—boxes without lines; acronyms without explanations; and a mixture of horizontal and vertical layers. None of them convey meaning effectively.

We’re engineers, of course, not artists, so in this Shortcut we’ll look at some of the key techniques you can use, including Brown’s C4 model and UML, alongside practical advice for how and when to use diagrams, and how to maintain them.

Standard Notion and Abstraction