One of the key problems in architecture documents is the idea illustrations are sufficient for explaining design.
Let me give you an example:
Eo---oP
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.
