Hitchhiker's Guide to Software Architecture and Everything Else - by Michael Stal

Wednesday, December 09, 2009

A picture can say more than thousand words - a word can say more that thousand pictures

One of the key problems in architecture documents is the idea illustrations are sufficient for explaining design.

Let me give you an example:


What could the diagram illustrate?

Could this describe a hydrogen atom consisting of a proton and an electron?

Does it represent the association between an entity bean and its persistence store?

Or is it something completely different?

Diagrams are models. They can only express a subset of reality. If you do not know the concrete context, you’ll have no way to figure out what the diagram actually means.  But if you are familiar with s special context, you might be inclined to map a diagram to your own context which, however, might be painfully wrong.

Thus, an architect should always explain the context of a diagram as well as the constituents and their meaning textually in the document.

What about the other way round?

Again, an example:

Component A is connected with B, C, D. D is connected with E and C. F is connected with D and A … a lot of more information …

In the example above, plain text is not really helpful. Here seems to be a good place to add a diagram that graphically illustrates the components and their connections. Text alone is not capable of describing complex structures which often appear in architecture design.

Hence, we recognize that diagrams need explanations to understand their semantics. Otherwise they just represent syntactic glibberish. In addition, UML, SysML and other graphical notations might lead to ambiguous illustrations which are open to interpretation. Thus, tell the reader what exactly the model behind the diagram is supposed to be.

As a consequence, all design documents that are automatically generated have almost no value.  For example, design rationale (such as requirements and their association with architectural decisions) is better described using textual language instead of diagrams.

Thus, use diagrams carefully in your design documents. But also be aware of text that does only describe what is depicted in diagrams, but does not introduce information such as pre- and postconditions, invariants, contextual information, design rationale, …

Guess, why there are UML use case diagrams that illustrate a set of use cases, but no graphical means for describing the use cases themself?

Use text and diagrams wisely! Don’t consider design documents as write-only-entities. You will see what I mean whenever you have to understand  documents of your fellow engineers.


  • You are absolutely right. A picture should be accompanied by a story that shapes the necessary context.

    By Anonymous Henk van Dijken, at 9:37 PM  

  • I have seen many cases where people point to a diagram and says "its all there", sometimes they've just produced a diagram (with a strange name) and no text at all, put in a (othewrwise empty) chapter in a document!

    I think the problem is when using specific tools and notation (such as UML) it gets too much attention in producing the graphical diagram instead of describing a problem/solution/context and enhanced the discussion (text) with some carefully drawn diagrams. Those people may feel afraid of not doing the right thing notationally, or they just dont se the point in drawing diagrams.

    Relax! Think again!! What text is necessary to enhance the diagram and what visual effects increases the understanging of a piece of text. So the result is better (1+1=3)...

    By Anonymous Anonymous, at 1:31 PM  

  • For sure! Models are used to make complex scenarios more simple, but not to explain all. Use notes wisely, but use, please!

    By Anonymous Wanderson Santos, at 10:00 PM  

Post a Comment

<< Home