There's a reasonably famous story about a PowerPoint slide that was shown to the commander of allied forces in Afghanistan in 2010 (shown below). Allegedly, he studied it for a short while, then announced “when we can understand that slide, we will have won the war.” The story provoked a slew of articles with titles like 'We have met the enemy and he is PowerPoint'. Unfortunately, that slide would have been at home alongside a few architecture diagrams that I've seen.
Summary: While a picture paints a thousand words, some architecture diagrams manage to be a lot clearer than others. I've seen hundreds of diagrams from dozens of organizations, and there are some common themes amongst the good ones. These are; restricted scope of diagram, separation into viewpoints if need be, proper arrangement of symbols, use of annotation, avoid using color to show information.
The first, and most obvious error in the McChrystal slide, one committed by numerous diagrams, is that it's just too damn big. Trying to digest it is like trying to eat an extra-large pizza by yourself – the mind chokes. I've run into more than one organization that has adopted giant diagrams that are literally a couple of meters on a side – and then they’ve proudly shown me the extra-large printer that they had to buy in order to print them out and decorate their walls with them.
The question is: who is going to use this diagram, and for what? If you’re not familiar with a diagram that complex, how will you be able to find the key points? And if you are familiar with the diagram’s subject matter, what does the diagram add? About the only valid use I’ve seen wall hangings like that serve is to convince management that the architecture is complicated. Which is arguably valid, but for communication of any other information – not so much. So, I recommend A3 maximum size (or 11x17 if you’re in North America).
Now, one common driver behind these gigantic diagrams is the wish to have one over-arching diagram that shows everything that someone needs to know about an architecture. But for the reasons that I stated above, it doesn’t work like that. The alternative is to adopt the approach of viewpoints as described in ISO 42010 and adopted by TOGAF and ArchiMate. In other words, create different perspectives for different audiences.
The next rule is one that you’ll find stated in many places, and I really restate it here purely for completeness’ sake – arrange your symbols on a grid pattern, and look to minimize the number of lines that cross. This is purely for the sake of legibility.
The next best practice that I’ve seen is to use a reasonable level of annotation to call out the key points. It’s possible to over-annotate, and you should not feel obliged to annotate every single element on a diagram, but the key points should be called out. One good rule is to borrow from Miller’s Law and aim for a maximum of seven key points.
Last of all, I’m also going to argue that you should avoid the exclusive use of color to convey information. The problem with doing so is twofold – there is the concern with disability legislation, and at the same time, it means that people who print out such diagrams to read lose information. Hence, if color is used, it should not be the only way that a piece of information is conveyed. By analogy, traffic lights do not only rely on colors – they use position as well (top light = stop, middle light = warning, bottom light = go).
Architecture is an inherently complex subject, and the diagrams that we create tend to reflect that – there’s no escaping this issue. However, by following a few guidelines, it’s possible to avoid needless complexity that if not addressed, can often obstruct the value of a diagram.