Assumed Audience: anyone who has drawn a system or software diagram; architects, engineers, developers
I came across this list of common software diagraming mistakes by IcePanel and was reminded of the days when I used to spend much of my day explaining complex systems. Diagrams were always involved but not always successful. As a result, there are a few tips I’d add to the list.
State your assumed audience
💡 Tip: Clearly articulate your assumed audience for each diagram.
One of the greatest challenges I had with my diagrams was not being clear about my assumed audience. This often resulted in diagrams being picked up and used in ways they weren’t intended or used without the necessary context. For example, an application interaction diagram does not necessarily give you insight into network segregation of infrastructure fault domains. Reading failure domains, or the lack thereof, into such a diagram can result in a cascade of invalid assumptions being made about the behaviour of your system. If there is a risk that your diagram will be passed around, or become lore. It is worth being clear who the diagram is for, and what existing knowledge or context you expect them to have.
For more on assumed audiences in a broader context, see this post by Chris Krycho.
Beware the aid to discussion
💡 Tip: If a diagram was drawn to support conversation it is unlikely that it will stand on its own and tell the same story. Be prepared to re-draw it.
When I hear people talk of systems diagrams, I tend to think of beautiful creations, those epic multi-layered Visio drawings with toggles to enable layers for network, data, security, ownership, etc. I think of a finished work that articulates in intricate detail the inner workings of a system. The majority of my diagrams I ended up drawing were quite different. They were drawn on the spur of the moment, often with an sorry excuse for a whiteboard marker on a board that could have done with a good clean. They were far from beautiful and far from complete. Importantly, they couldn’t be considered accurate. They were an abstraction, simplified because the accompanying conversation included detail that did not need to be captured in diagrammatic form.
These diagrams were often drawn to support an evolving solution as ideas were tested with peers. These diagrams weren’t meant to last and were often rubbed out at the end of the conversation - except they weren’t. There was always that photo subsequently uploaded to a wiki or included in a document that quickly became a source of truth. That photo gave the diagram a life beyond the original intent. It would have been better to re-draw.
No Substitute for Explanation
Tip: Don’t send a new team member a system diagram. Sit (or stand) with them and re-draw it in real time. Discuss as you go. You can always send them the master copy afterwards.
As new people joined our teams, they would often be sent the “Technical Architecture” or “Solution Design” as a way to familiarise themselves with the systems they’d be working with. This was lazy on-boarding. No one enjoyed staring at a diagram trying to make sense of the many boxes and lines. And, whilst a picture may be worth a thousand words, a diagram, no matter how well drawn, is no substitute for an explanation. A complex diagram requires context and I quickly found that there is no substitute for taking the time to sit with a new team member and let the diagram unfold along with the discussion.
It is true that no two versions of the drawing were ever the same. But an added benefit of this exercise is that it gave me a chance to iterate on my explanations to catch assumptions that we’d made that now proved to be invalid. It forced me to keep diagrams fresh. For the new team member, we were able to focus on areas of specific relevance. Better yet, it was a chance to question and to challenge. On boarding was altogether more useful and infinitely more fun.