Software Architecture Documentation Coaching

Challenges:
How do you capture the software architecture for a system in a document that can successfully serve all of the architecture's stakeholders?

• How do you decide which architectural views to document?
• What information do you record about an architectural view beyond just the graphical box-and-line diagram or "cartoon"?
• How do you specify an architectural element's software interface? What information do you record?
• What information beyond views must be recorded? What information applies to more than one view? How do you record the relationship among views?
• How do you specify an element's behavior?
• What notations are available for documenting an architecture, for documenting a view, for documenting an interface, for documenting behavior?

Overview:
A software system's architecture may be its most crucial determinant of success or failure. Without an adequate architecture that delivers required function as well as quality attributes, the project will fail. But even the best architecture is of absolutely no value if it is not effectively communicated to those who require it: designers of finer-grained components, implementors, testers, performance engineers, security analysts, builders of interfacing systems, and a host of others. In spite of the plethora of materials about languages with which to document system designs (notably UML) and a growing abundance of information about architecture concepts, there is almost no guidance available for how to record the necessary information about an architecture so that its value to a project is realized. An SEI team has devoted a major, multi-year effort to crafting and codifying guidance for documenting a software architecture. The result of that work is an approach we call "Views and Beyond".

Benefits:
Documentation coaching can help a software development organization avoid the pitfalls of inappropriate or incomplete or vague documentation. Many have experienced the frustration of committing a massive expenditure for documentation, only to have the resulting artifacts gather dust on shelves. This is the result of documentation that has not been properly planned and aimed more at satisfying standards than satisfying stakeholder needs. Coaching can prevent this situation by raising documentation and documentation planning to a level commensurate with its importance.

Who Would Benefit:
Software architects and the people to whom they must communicate the architecture will benefit: designers, implementors, technical managers, testers, analysts, quality specialists, and others. In short, every member of a software development project can gain.

Description:
Documenting a software architecture is a matter of documenting the relevant views, and then adding information that applies across views. A first step is to choose the relevant views, and this choice in turn depends on the anticipated usage. Documentation may be used to drive analysis, to constrain an implementation, to manage a project, or to convey an introductory overview of a system. Documentation is also used as a vehicle for communication to and among stakeholders. We work with the client to articulate the anticipated uses of the documentation, and the stakeholders that will carry out those uses. If appropriate, we can facilitate the holding of a stakeholder workshop to nail down the choice of views. Once the views have been selected, we can provide templates and documentation guides for each view, as well as guidance about how views are related to each other, and pitfalls associated with mis-using each kind of view.

Documentation that applies across views follows a simple how-what-why approach: How the documentation is organized to serve stakeholders, what the architecture is, and why the architecture is the way it is (i.e., design rationale).

In addition to documenting the structure of the system, an architect must also document interfaces and behavior. We also provide guidance for documenting dynamic or highly variable architectures, as well as guidance for combining views to produce information-packed hybrid views.

Availability:
SEI staff will work with a customer team to understand the specific situation and undertake the best coaching approaches that are appropriate.

Additional Information:
Contact us for additional details or to arrange software architecture documentation coaching services.