Improve Your Technical Diagrams
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
Get Improve Your Technical Diagrams now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
