Part II. Beyond Structure: Completing the Documentation
Part I presented a substantial repertoire of useful architecture styles. An architect can choose from among these styles, pick styles in other style catalogs, or design a new style. Once a style is chosen, the view based on it needs to be designed and documented. The chapters in Part I presented ways to document the elements and relations that populate a view.
But documenting a view involves more than just writing down (or more often, drawing) the elements and their relations. Elements have interfaces, and those need to be documented so that teams developing other elements can interact with them correctly. Elements have behavior, and confederations of elements have collective behavior, which needs to be documented so that implementers know what the elements they’re coding should do, and so that analysts can tell if the architecture is satisfying the system’s behavioral requirements. Architects need a way to explain their design—what drove them to make the design decisions they did. Documenting rationale is a critical but often underpracticed part of an architect’s duties.
Great things are not done by impulse, but by a series of small things brought together.
—Vincent van Gogh
These and other kinds of information are important parts of the architecture document. Part II deals with those.
• Chapter 6 explores documentation techniques such as refinement and chunking of information, context diagrams, creating and documenting combined views, documenting variability and dynamism, and documenting the rationale behind architectural decisions.
• Chapter 7 tells how to document the interfaces of architecture elements. It provides ways to document the existence of interfaces, the syntax (or signature) of an interface, and the semantics of an interface.
• Chapter 8 explores another essential technique for architects: documenting the behavior of an element or an ensemble of elements. Documenting behavior is an essential counterpoint to documenting static structure. This chapter covers the techniques and notations available for expressing the behavior of elements, groups of elements, and the system as a whole.