Good Architecture Descriptions are Explosive

Good architecture descriptions are explosive! Like C4, the architecture description can shake things up, remove roadblocks, and create opportunities where none existed before. In order to have this impact, the architecture description - the Software Architecture Document (SAD) - must be Correct, Clear, Concise, and Comprehensive. It must be C4!

As we touched on in "What is Software Architecture?," it's essential that the architecture of a software-intensive system be appropriately documented and communicated. In "The Most Important Competencies of the Software Architect," we discovered that communication is one of the most important skill groups for the Software Architect and identified the following communications competencies:

• Understand stakeholder needs
• Ensure the stakeholders understand the capabilities and limitations of the architecture
• Gain consensus on approach through diplomacy, compromise, and mediation

A quick look at the communication competencies immediately suggests the pivotal role of the Software Architecture Document (SAD). An effective SAD is essential in gathering consensus and ensuring universal understanding among the community of stakeholders.

Of course, at its core, the SAD is an assembly of models, each representing key dimensions of the architecture. These models are necessarily abstractions of the actual software system, and serve to encourage breadth of understanding, establishing context and meaningfulness to the many stakeholders. As abstractions, though, the models are somewhat removed from reality. In his book on Analysis Patterns, Martin Fowler addresses this concept in a claim that "Models are not right or wrong, they are more or less useful." The authors of Software Systems Architecture expound on the idea and argue convincingly that "Every architectural model is an approximation of reality. In other words, it is only partially accurate and partially complete."

Given the nature of the SAD as a series of abstractions, it can sometimes be a challenge to decide what content is appropriately included in the Software Architecture Document and what is better left for other (important but separate) artifacts. To help encourage good decisions in this area, it can be helpful to pursue an "Explosive" architecture description that maximizes the four C's:

• Correct - Accurate content describing the right architecture
• Clear - Easily understood and meaningful to the stakeholders
• Concise - Includes only the architecturally significant content
• Comprehensive - Addresses the true breadth of architectural concerns

Correct

Arguably "Correctness" is the foremost quality of a Software Architecture Document. The SAD is one of the most critical tools for ensuring consensus among the stakeholders. By accurately representing the needs and concerns of the stakeholders and mapping those concerns into the solution space, the Software Architect is able to validate consistent understanding of the needs and ensure they're accurately satisfied by the architecture.

To gain full benefit of the architecture description, the SAD must be kept up to date. This ensures that the right inputs are being considered and encourages good decision making. Keeping the SAD up to date requires the integration of effective processes into development, operational, and support plans.

Clear

In order to be effective as a communication vehicle, the SAD must be written in clear and straightforward language and organized/structured in a manner that promotes the ability of each stakeholder to understand the relevant parts. To accomplish this goal, the Software Architect must demonstrate two things to each stakeholder (or stakeholder group): 1) The needs of that stakeholder are accurately understood, and 2) The needs are met by the architecture. As different stakeholders have different interests, it's essential to structure the SAD in a way that accommodates the various perspectives. A common approach to dealing with this factor is the use of multiple views such as described in "The 4+1 View Model of Software Architecture" promoted by the Rational Unified Process and Phillipe Krutchen (http://www.win.tue.nl/~mchaudro/sa2004/Kruchten4+1.pdf).

In addition to multiple views and perspectives, a SAD is typically more clear when you go out of your way to establish business and technical context and to tailor the content, language, and detail to the audience's skills and experience.

Concise

Of all the SAD quality attributes, "conciseness" is one of the most difficult to achieve. But it's also one of the most important. In fact, a SAD that comes up short in conciseness is likely to come up short in other dimensions such as correctness and clarity. By carefully calibrating the level of detail represented in the SAD, the Software Architect fine-tunes the clarity of the document and makes it more meaningful to the stakeholders. Essentially, this is an exercise in maximizing the purity of the architecture description, aggressively fending off the fluff and maximizing the signal-to-noise ratio.

When the SAD is effectively concise, it represents only those characteristics of the system that are truly architecturally significant. This means, as we progress more deeply into a software project, the SAD becomes more and more stable (as the architecture becomes stable) and the document is easier to keep current. This reduces the effort associated with the maintaining the document and maximizes its value, both during the project and throughout the life of the product.

Comprehensive

Comprehensiveness can be the opposite of conciseness, so we see here one of the many balancing acts played by the Software Architect. To be effective, the SAD must include the full scope of business and technical concerns and establish a clear context for their understanding and evaluation. These concerns must then be analyzed and addressed with sufficient precision and detail to encourage strong stakeholder review and support the ongoing implementation of the system.

In "What is a Software Architect," we identified the role of the Software Architect as:

• The software architect has overall responsibility for driving the major technical decisions, expressed as the software architecture. This typically includes identifying and documenting the architecturally significant aspects of the system, including requirements, design, implementation, and deployment "views" of the system.


• The architect is also responsible for providing rationale for these decisions, balancing the concerns of the various stakeholders, driving down technical risks, and ensuring that decisions are effectively communicated, validated, and adhered to.

Successful Software Architects recognize the need for an explosive Software Architecture Document that maximizes the four C's.