Motivating Architecture

Software Architecture and Related Concerns

The Architecting Process

The Role of the Architect

Architecture in  Context

Architecture Training

Software Architecture Class

- Chicago, IL April 6-9, 2009

Enterprise Architecture Workshop

- TBA

Role of the Architect Workshop

- Indianapolis, IN April 27-29, 2009

Enterprise Architecture Seminar (1-day)

Architecture Overview Seminar

Architecture Requirements Workshop

Action Guides for Architecture Specification

Architecture Documentation Goals

• Recording the architects' decisions. To meet this goal, the documentation must be complete and unambiguous. We present a suggested architecture specification format and some of our Action Guides to help you address this goal.
• Communicating the architecture. For each of your stakeholders, consider what they need to know, and how best to convey what they need to know. A single, comprehensive architecture specification document is probably going to become shelfware and will not serve the goal of communication.     

Architecture Drivers

Though not part of the architecture as such, the drivers that shape the architecture are important to record and communicate. They include:

• Architecture Vision, expressing the desired state that the architecture will bring about. See the Vision Graphic Guide from Grove Graphics International. It provides a great way to collect group inputs to a vision, and to organize vision elements.
• Architectural Requirements, capturing stakeholder goals and architecturally significant behavioral (functional) requirements as well as system qualities (non-functional requirements) and constraints. See our Stakeholder Profile Action Guide and  Use Case Action Guide.
• Assumptions, Forces and Trends, documenting assertions about the current business, market and technical environment now and over the architecture planning horizon.  
• Architectural Principles, expressing a choice of direction or approach to guide architecture decision making. See our Principles Action Guide.
• Organizing Metaphor, Key Concepts, Mechanisms, Styles (or architectural patterns). 

Architecture Views

We use different views to enhance the understandability of the architecture and to focus on particular concerns separately.

• Structural View. If we accept that "architecture is the high-level structure of the system comprised of components, their interrelationships, and externally visible properties" (adaptation of the Bass, Clements, Kazman definition), the structural view is central. It consists of the Architecture Diagram, and Component and Interface Specifications. 
• Behavioral View. In decomposing the system into components and designing their interfaces, we have to answer the question "How does this work?" Likewise, in understanding and using the architecture, we have to be able to answer the same question. This is the role of the behavioral view, with its Component Collaboration or Sequence Diagrams. 
  
• Conceptual Architecture. The purpose of the conceptual architecture is to direct attention at an appropriate decomposition of the system without delving into details. Moreover, it provides a useful vehicle for communicating the architecture to non-technical audiences, such as management, marketing, and users. It consists of the Architecture Diagram (without interfaces) and an informal component specification (which we call CRC-R cards) for each component.
• Logical Architecture. The logical architecture adds precision, providing a detailed "blueprint" from which component developers and component users can work in relative independence. It incorporates the detailed Architecture Diagram (with interfaces), Component and Interface Specifications, and Component Collaboration Diagrams, along with discussion and explanations of mechanisms, rationale, etc.
• Execution Architecture. An execution architecture is created for distributed or concurrent systems. The process view shows the mapping of components onto the processes of the physical system. The deployment view shows the mapping of (physical) components in the executing system onto the nodes of the physical system.

An Architecture Decision Matrix provides traceability between the architecture drivers and the decisions reflected in the various architecture views. 

We encourage using UML models where applicable (stereotyped Class Diagram for the Architecture Diagram, stereotyped Collaboration Diagrams for Component Collaboration Diagrams, etc.), as this provides a standardized notation and there is tool support.

Architecture Documentation

Architecture is, by nature, created by the few for the consumption of the many. You cannot bring "the many" into the process directly, so documentation is an important vehicle for communicating the architecture and educating the development community during design ramp-up, and clarifying decisions and resolving issues later on. 

It is important to record the reasoning behind architectural choices along the way. This reasoning includes providing traceability to the driving forces behind the decisions (including business strategy, product requirements, etc.), the tradeoffs that were explicitly dealt with, and the experience, modeling and analysis that was brought to bear as alternative approaches were weighed. Later you can tailor your documents for different audiences, but if you neglect to provide a record as you go, you will have more work to do trying to resurrect the assumptions and assertions, rationale and reasoning that explain the architectural decisions. In short, DON'T leave documentation until the end!

With the architecture drivers and various architecture views, you have the raw material from which to compose documents and presentations targeted at different audiences. These include:

• Reference Specification. The full set of drivers, views, and supplements such as the decision matrix and issues list, provides your reference specification. 
• Management Overview. For management, you would want to create a high-level overview, including vision, business drivers, Architecture Diagram (Conceptual) and rationale linking business strategy to technical strategy. 
• Component Documents. For each component owner, you would ideally want to provide a system-level view (Logical Architecture Diagram), the Component Specification for the component and Interface Specifications for all of its provided interfaces, as well as the Collaboration Diagrams that feature the component in question.

Outcomes, Not Just Deliverables

For an architecture to be good, right and successful, we cannot focus on deliverables alone. In particular, we need to ensure that intangible outcomes like attitude shifts and understanding do not get brushed aside in the effort to produce "deliverables." We have encountered architects who actually believe that their manager is judging their effectiveness based on the number and size of documents produced, since this is the visible workproduct of architecture. Indeed, in the absence of all other feedback, this is what your manager will have to fall back on. But the more positive "buzz" you generate in the organization, the more your manager will rely on intangible signals of intangible progress. And the longer you have been in this architecting game, the more you recognize that it is the intangibles that lead to success or failure.

Yes, we need documents that provide a formal "organizational memory," that serve as a reference, and a medium to judge whether the architecture is good and right. They help determine whether we are ready to move to the next stage. They also serve as medium for broadcast to achieve broader understanding and buy-in than we might have the bandwidth to achieve through one-on-one contact. Some time in the future, the architecture specification may be enough, but in the foreseeable future, success for architecture is most likely going to mean you have to overcome resistance, educate, negotiate, coax and cajole, working formal and informal avenues of influence to achieve acceptance and readiness to apply the architecture.

References

Bachmann, Felix, L. Bass, J. Carriere, P. Clements, D. Garlan, J. Ivers, R. Nord, and R. Little, Software Architecture Documentation in Practice: Documenting Architectural Layers, draft available at http://www.sei.cmu.edu/publications/documents/00.reports/00sr004.html

IEEE 1471 Recommended Practice for Architectural Description http://standards.ieee.org/reading/ieee/std_public/description/se/1471-2000_desc.html

Malan, Ruth and Dana Bredemeyer, "Software Architecture: Central Concerns, Key Decisions", (ArchitectureDefinition.PDF, 124kb), May 2002.

Malan, Ruth, and Dana Bredemeyer,  "The Visual Architecting Process" (VisualArchitectingProcess.PDF, 65kb), February 2002.

Malan, Ruth, and Dana Bredemeyer,  Software Architecture Action Guide Book (draft): http://www.bredemeyer.com/ArchitectingProcess/SWAActionGuideTOC.htm

Malan, Ruth, and Dana Bredemeyer, Visual Architecting Process: Interactive Guide,  http://www.bredemeyer.com/ArchitectingProcess/VisualArchitectingProcess.htm

Malan, Ruth, "Architecture Documentation: Courage to Fly in the Face of Convention," A Trace in The Sand blog post, July 24, 2006.

Ogush, M., D. Coleman, and D. Beringer, "A Template for Documenting Software Architectures", March 2000, available on http://www.architecture.external.hp.com/Download/download.htm

SEI Software Architecture Documentation Template, http://www.sei.cmu.edu/architecture/SAD_template2.dot

Youngs, R., D. Redmond-Pyle, P. Spaas, and E. Kahan, "A Standard for Architecture Description", IBM Systems Journal, Vol 38 No 1. http://www.research.ibm.com/journal/sj/381/youngs.html

UML References

Booch, G., J. Rumbaugh and I. Jacobson, The Unified Modeling Language User Guide, Addison-Wesley, 1999.

Rumbaugh, J., I. Jacobson and G. Booch, The Unified Modeling Language Reference Manual, Addison-Wesley, 1999.

The official OMG Unified Modeling Language (UML) Documentation is available at http://www.rational.com/uml/index.jtmpl

Action Guides

Our workshops cover our full set of Action Guides (including models, templates and heuristics), and go into creating and documenting architectures:

• Software Architecture Workshop
• Modeling Architectures Using UML and Action Guides

UML is a trademark or registered trademark of the Object Management Group, Inc. in the US and other countries.

Restrictions on Use: All material that is copyrighted Bredemeyer Consulting and published on this page and other pages of our site, may be downloaded and printed for personal use. If you wish to quote or paraphrase fragments of our work in another publication or web site, please properly acknowledge us as the source, with appropriate reference to the article or web page used. If you wish to republish any of our work, in any medium, you must get written permission from the lead author. Also, any commercial use must be authorized in writing by Bredemeyer Consulting.