NEWS AT SEI
This article was originally published in News at SEI on: June 1, 2003
Every day, in organizations around the world, thousands of dollars are invested to design and build software architectures, only to result later in architectures that can’t be reproduced, repaired, analyzed, or even implemented due to poor documentation or a complete lack of it. In the past, no one seemed to know what makes good software architecture documentation. Though many books described the languages used to create it, none addressed its content or purpose. Typically the question of how to document a software architecture was answered by identifying how not to do it, leaving documenting as a trial-and-error process—sometimes with costly consequences.
Researchers at the Software Engineering Institute tackle the issue of software architecture documentation in a new book titled Documenting Software Architectures: Views and Beyond. This book, which was just awarded a Jolt Productivity Award from Software Development magazine, strives to answer the critical question, How do you document an architecture so that others can successfully use it, maintain it, and build a system from it?
What Is a Software Architecture?
A software architecture is the structure or structures of a system, comprising elements, their externally visible properties, and the relationships among them all. Documenting software architecture is important because it serves as the blueprint for a system and the project that develops that system. It defines work assignments and is the primary carrier of quality attributes (e.g., performance, reliability, security, and modifiability), the best artifact for early analysis, and the key to post-deployment maintenance and mining. So it makes sense that documenting an architecture is the crowning step to creating it.
Because software architectures are too complicated to be seen all at once, documenting them using views is a helpful technique. A view is a representation of some of the system’s elements and the relationships associated with them. The most fundamental principle of architecture documentation comes from the concept of views: Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view.
While some software architects prescribe using standard views for a particular type of system, Documenting Software Architectures recommends using an approach that incorporates input from the stakeholders (those who have a vested interest in the system, such as developers or subcontractors). Such input tells architects how the documentation will be used and what stakeholders expect from it. Ultimately, this input helps the architects decide which information should be part of a software architecture’s documentation.
Knowing Which View to Use
Which views are relevant for a particular software architecture depends on who the stakeholders are and how they plan to use the documentation. Software architecture documentation has three primary uses: as a resource for educating infrastructure support personnel, new stakeholders, future architects, and others about the system; as a vehicle of communication among stakeholders; and as the basis for system analysis. For example, if future architects will use the documentation to gauge the impact of an expected change, a uses view (showing which modules are required for the proper operation of certain parts of a system) and a decomposition view (showing how a system’s responsibilities are partitioned across modules) would be relevant.
For nontrivial systems, one module view (showing elements that are units of implementation) is typically used, as well as one component-and-connector view (showing elements with runtime behavior and interaction), and one allocation view (showing how software structures are allocated to non-software structures).
Views of large software systems might contain hundreds or thousands of elements, so architects need to break the information presented into manageable chunks called view packets. A view packet is the smallest cohesive bundle of documentation that would be given to a stakeholder. It can show broad areas of the system at slight depth or small areas of the system at great depth. To orient the reader looking at a view packet, context diagrams are also included in the software architecture documentation. These diagrams depict the system or part of the system explained by each view packet.
Sound software architectural documentation should also show how views are related to each other through a combined view or a bridging document that relates elements and relationships.
Additional Documentation Components
Once software architecture is documented through views, it is necessary to add seven additional components to the documentation:
- a documentation roadmap that tells how the documentation is organized, lists the views used and their elements, and provides scenarios for determining which parts of the documentation to consult
- a view template that explains how each view is documented and organized
- a system overview that provides context for new architects through an informal description of the system, including its purpose and functionality
- mapping between views, which establishes useful correspondence between them
- a directory, which shows where each element, relationship, and property is defined and used
- an architecture glossary and acronym list
- background information, design constraints, and rationale
These components are described in detail in Documenting Software Architectures.
Architecture Documentation Protects Your Investment
For nearly all systems, quality attributes are every bit as important as making sure that the software performs its expected functions. Architecture is the means by which these quality attributes are built into a system; in documentation, the formula for achieving them is put down on paper. Using Documenting Software Architectures as your guide, you can create sound software architecture documentation that will protect the investment made during hours of design and decision making, and ultimately protect the intellectual property of your organization.