Five ways to communicate more effectively with software architecture diagrams

Explaining simple things can be very complicated.

Architectural diagrams allow for discourse, conveyance of information and abstraction of the organisational software engineering edifice. To many, they are a critical component of how to barter for buy-in during a design phase or to conceptualise future roadblocks before the implementation period. They are also a visual footprint that not only serves for posterity but helps to encapsulate the thought processes of the author.

If you spend a significant amount of time communicating complex ideas through architectural diagrams you’ll likely have found a few keys habits that help you successfully convey concepts. In this post, I want to share my key tips for successfully using diagrammatic aids to drive conversations with engineers and non-engineers alike.

Display just enough to convey the exact sentiment.

1. Choose your tooling carefully

I have spent many hours looking for the perfect diagramming tool. I still haven’t found it, but there are some that come close. Your choice of tooling sets the tone for how you work to produce your diagrams. Choosing something that is built for collaboration has a stark contrast to offline or solutions that require a level of domain knowledge ( Mermaid diagrams are commonly generated from markdown syntax and require expertise within the domain-specific language). Your tooling also either enables you to capitalise on changes within a meeting or forcing you to work offline and disconnected.

Here are some of the criteria I use to determine whether the software is worth investing in:

• Price. Sounds obvious but I am only willing to pay for a recurring fee if it’s absolutely worth it — they also need to be clear about data retention after I decide to stop paying.
• Portability. Web-based software is a must and should work on a multitude of user-agents (you never know when or where you’ll be referring to these).
• Multiple export types and ability to have a high fidelity of cropping ( essential for later editing or embedding into pdfs, slack or presentations)
• A large set of icon templates relevant to my world ( cloud-native infrastructure) and publicly importable sets ( google cloud / AWS lucid chart icons )
• Highly configurable relationship tools and cardinality icons.
• Visually intuitive UX should be a given but many platforms make you labour through sub-menus to perform simple activities.

2. Be consistent with styling; be beautiful and engaging

• Symmetry is important. It directs the balance of the diagram and indicates where you want the viewer to look. Harmonious lines and well defined geometric shapes will bring a sense of tranquillity and professionalism to the document.
• Colourways will set the tone for the focus. Systems or services in red, innately draw the eye and indicate an issue. Use muted colours to frame the backdrop and blues and greens to show API flow or desired interconnectivity. The psychology of colour is deep-rooted within human behaviour and you should leverage this to evoke emotion and action through your architectural diagrams.

Colour theory is at play even when illustrating this data storage architecture. We are influenced and able to influence with our associations to colour ( The muted pastel tones intentionally create a calm and clear illustration).

• Capitalise on existing icon-sets and templates. At the time of writing, I know that both draw.io and Lucidchart support AWS/GCP icon sets and default templates. Sticking to a recognisable style will help break down initial cognitive disconnect whilst viewers understand your diagram.

• Boxes are our friend. A box can be a service, a repository, a process or any other number of things. But try to think of boxes as domain boundaries or discrete components. This can help encourage the use of other iconographic references, surface an opinionated decision on representing a concept and break-away from the stereotypical diagram look ( driving engagement with the viewers and participants in meetings ).

Take a completely flat and undescriptive diagram like below…

With a few small changes and adding pertinent information to the narrative, it becomes this…

With a few small but powerful changes, we’re including other information that previously would have been tribal knowledge. Equally, through use of colour, we are able to subtly illustrate a point or focus feedback on a particular system component or relationship.

3. Use visual landmarks to help all audience types find a reference point

• Direct the viewer's attention with labels and the right verbiage.
• Utilise well-known product icons for an association of brand.

These products are well known and so are the associations of what they do. Do consider layman viewers and colleagues from other areas of the business before neglecting to use labels.

• Explain things well, use full names. Do not assume everyone is an expert. Work with the premise that you’ll be showing this off to non-technical folk who are just as smart as you, but won’t know the acronyms for everything.

Use clear language and bring to light the components pertinent to the conversation.

4. One narrative per diagram; don’t get lost in the minutia

• The key here is to display just enough information to be useful. To explain a problem or improvement visually that is reductive enough to still carry the original sentiment.
• There is a common itch to revisit and elaborate on diagrams with additional arrows and boxes, but these rarely add value but rather dilute the meaning of the visualisation.
• If it is a choice between detail and artistry; choose to break down the detail into several self-contained and well-illustrated documents. It will improve the quality of the conversation around them and help to mentally map them as layers within the architectural space. The artistry and beauty of a diagram are functional and is to enable clearer expression.

This is a fairly bog-standard type of architecture diagram that someone might create to represent some API flow.

Let’s revisit the above diagram using some of the pointers we’ve discussed so far…

This diagram has structured the content in a way that draws the viewer to hone in on the processes around the consumers. This is done by using simple visual clues and providing data upfront to avoid discussions around prior art ( e.g. What is the hosting solution? Where is our PII data stored? Who owns the parts of the system?)

5. Treat the diagram as a living document

• Open the document in edit mode, this will allow you to alter transparency and blow-up components that need group participation or clarity; leading to the development of a clear lexicon.
• Gauge the participation with other engineers when you present architectural designs. Start at the macro level and assess whether your team prefer a wholistic solution discussion or whether it is, in fact, more productive to break out into small outcome-focused diagrams.

An architectural diagram is not set in stone. It is a tool for conveying an idea and these can evolve over time.

Visual aids are powerful tools in articulating the most complex concepts. Software engineering architectural schematics are no exception to this.

I advise you to try to convey concepts as concisely as possible and to consider the viewer or recipient when trying to convey your sentiment. The above steps are suggestions on how to build your own set of practices and behaviours to encourage participation and discourse; ultimately benefiting the quality of the proposed system.

You shouldn’t be uneasy about any parts of the architecture.

It shouldn’t
contain anything just to please the boss. It shouldn’t contain anything that’s hard for you to understand. You’re the one who’ll implement it; if it doesn’t make sense to you, how can you implement it?”
― Steve McConnell, Code Complete

If you liked this let me know on twitter @AlexJonesax

Thank you!