Writing architectural documentation is much like other types of writing. You must understand the uses to which the writing is to be put and the audience for the writing. Architectural documentation serves as a means for communication among various stakeholders, not only up the management chain and down to the developers but also across to peers.
Architecture is a complicated artifact, best expressed by focusing on particular perspectives depending on the message to be communicated. These perspectives are called views, and you must choose the views to document, must choose the notation to document these views, and must choose a set of views that is both minimal and adequate. This may involve combining various views that have a large overlap. You must document not only the structure of the architecture but also the behavior.
Notations for documenting views differ considerably in their degree of formality. Roughly speaking, there are three main categories of notation:
Informal notations. Views are depicted (often graphically) using general-purpose diagramming and editing tools and visual conventions are chosen for the system at hand. The semantics of the description is characterized by natural language, and they cannot be formally analyzed. In our experience, the most common tool for informal notations is "PowerPoint".
Semiformal notations. Views are expressed in a standardized notation that prescribes graphical elements and rules of construction, but it does not provide a complete semantic treatment of the meaning of those elements. Rudimentary analysis can be applied to determine if a description satisfies syntactic properties. "UML" is a semiformal notation in this sense.
Formal notations. Views are described in a notation that has precise (usually mathematically based) semantics. Formal analysis of both syntax and semantics is possible. There are a variety of formal notations for software architecture available. Generally referred to as "architecture description languages (ADLs)", they typically provide both a graphical vocabulary and an underlying semantics for architecture representation. In some cases, these notations are specialized to particular architectural views. In others, they allow many views or even provide the ability to formally define new views. The usefulness of ADLs lies in their ability to support automation through associated tools: automation to provide a useful analysis of the architecture or assist in code generation. In practice, the use of such notations is rare.
Schmucks and Jerks
One day A compiler guru. He was recounting some of his favorite war stories from his long career. One of these stories is a good example of the way as software engineers and an architect you should document your code. this guru was talking about the time that he was chasing down a very nasty and subtle bug in the code of a compiler that he was maintaining. After a long and exasperating search, he finally located and eventually fixed the bug. But the search itself had gotten him so worked up, and he was so infuriated at the irresponsible thought and programming that led to the bug, that he decided to do a bit more detective work and figure out who was the jerk responsible for that bug. By going back through the revision history, he found the culprit. It was him. He was the jerk. It turns out that he was the one who—eight years earlier—had written that offending piece of code. The trouble was, he had no recollection of writing the code and no recollection of the rationale for writing it the way he had done. Perhaps there was a good reason to do so at the time, but if so it was lost now. That is why we document. The documentation helps the poor schmuck who has to maintain your code in the future, and that schmuck might very well be you!
Summary
Determining which form of notation to use involves making several tradeoffs. Typically, more formal notations take more time and effort to create and understand, but they repay this effort in reduced ambiguity and more opportunities for analysis. Conversely, more informal notations are easier to create, but they provide fewer guarantees. Regardless of the level of formality, always remember that different notations are better (or worse) for expressing different kinds of information. Formality aside, no UML class diagram will help you reason about schedulability, nor will a sequence chart tell you very much about the system’s likelihood of being delivered on time. You should choose your notations and representation languages always keeping in mind the important issues you need to capture and reason about.
Top comments (0)