Communicating Architecture through Diagrams


If you are an enterprise (technical) architect, then you will have definitely come across the case where you have masterfully explained how your system is put together, and why, only to realize some time later how misunderstood you have been.

You could throw up your hands in disgust with boisterous outrage as to how stupid everybody is (except for you of course) and how you cannot possibly expect to get anything done in this environment!

Or you could get very introspective and try therapy (if you think it will help).

Or you can just accept the fact that almost every technology problem we face today is just plain complex, and the words we use to describe our brilliant and less-than-brilliant approaches are not precise to get the point across. And even if you do reach some the audience, the bulk of what you have said may not survive a night of sleep.

They say “a picture is worth a thousand words” and where technology architecture is concerned, the old adage is pretty much true. I have often sat in discussions where one technical person described in detail how a system worked, while the other nodded in agreement, both absolutely sure they knew what each other was talking about.

That is until I went up to the whiteboard and drew out my interpretation of what both said only to see head nods and head shakes, but at different times.

“People do not communicate”

The conclusion, I reached (as well as others) is that a good diagram is much more expressive and precise when it comes to expressing technology architecture and design than any words can be. When I looked around at what people were using to create diagrams, the number of styles, ideograms and metaphors used was astounding. The same person would even use different styles in different documents. While better than words, it was still not good enough.

Think about two people speaking to each other using words where they have not a priori agree the meanings. If this were the case, communication, while expressive, would be fraught with imprecision and misinterpretation (kind of what happens now in I.T.)

Luckily, there are a few diagramming styles that are fairly widely used, fairly well defined, extensible and flexible. One of these is the UML (Unified Modeling Language). The specification (in multiple parts) is managed by the OMG (The Object Management Group). UML, while very, very useful is actually targeted primarily for the process of systems design rather than architecture and as such tends towards more detail. To use UML in the architecture process, we amust bstract away certain details in order to draw higher level parallels and patterns.

My favorite analogy to describe the difference between architecture and design maybe found here:” Blog: The difference between architecture and design”.

In order to use UML effectively for the purpose of diagramming architecture, we therefore need to be very clear about what we really mean when we use UML design elements. The clearer, more precise and more descriptive we are, the more information we carry in a single diagram.

To this end, I’ve posted a “style guide” for using UML for the purpose of describing Logical (Functional) Architecture here: http://pro.iankoenig.com/docs/LogicalArchitecturalDrawingGuidelinesv2.pdf
There are accompanying Shapes for Microsoft Visio that may be downloaded from here: http://pro.iankoenig.com/visio.php.

The style guide with accompanying shapes provide a fairly complete way of describing Logical Technical Architecture through diagrams, using only three of the thirteen diagram types in UML 2.0.
This style guide only covers “Logical (Functional) Architecture”. It does not cover: Information Architecture, Physical Architecture or Business Process Architecture

Leave a Comment