Effective architecture diagrams

Recently, I was working with Steve Ross-Talbot for a new client. We received a large number of documents describing the architecture that was to be implemented.

I noticed that, in order to assimilate this information, he took the same approach that I did which was to abstract the information upwards into a single simple diagram that captured the entire architecture in about seven blobs. He then took each blob and exploded this into further diagrams each with about seven blobs until he had an understanding of the problem area.  The result was a concise and easily comprehensible story at increasing levels of detail that was easier to follow and understand than the original.

We had a discussion about this and noted that in our experience we rarely see architects develop simple sequences of structured diagrams that tell a comprehensible and compelling story.  Instead we see diagrams with confusing inconsistencies in style and far too much information.  A set of diagrams should tell a story - there should be an obvious start, middle and end.  They should stand alone without the need for a narrator - a picture should not require a thousand words to explain it.

Rather than put my own tips for diagramming, I have deferred to an expert and added a link on the site to "Whiteboards that Work” by Bill Branson which contains a range of communication best practices.

Comments

[wpbarr]

Thanks for pointing out a great site, Alan.

[Steve Ross-Talbot]

Thanks for the blog. It is nice to read that ones instinctive approach is the same as others. Maybe this can be turned into a useful process and set of artefacts for architects in similar positions as we found ourselves in.

I was somewhat surprised that no overall simple diagram of what this client wanted to achieve was readily available and I was also surprised at the lack of consistency it their documentation.

But we always seem to have to deal with such matters and seek to normalise them.

[Mark Ridgwell]

Thanks for this refreshing piece of common sense.

People have a tendency to over-complicate things don't they? Keeping it simple, speaking in a language that everyone understands is a key to project success.

Kind regards,
Mark