Views and Beyond Collection
The SEI has a proven approach to documenting software architecture called Views and Beyond. These are some key publications about Views and Beyond.
Software Engineering Institute
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 communicating an architecture to its stakeholders is as important a job as creating it in the first place. An architecture must be understood so that others—designers of finer grained components, implementers, testers, performance engineers, security analysts, builders of interfacing systems—can build systems from it, analyze it, maintain it, and learn from it.
The SEI has a proven approach to documenting software architecture called Views and Beyond, or V&B. The name emphasizes that we use the concept of a view as the fundamental organizing principle for architecture documentation. A view represents a set of system elements and the relations associated with them. Views represent the many system structures that are present simultaneously in software systems. The basic principle of V&B is that documenting a software architecture involves documenting the relevant views, and then documenting the information that applies to more than one view.
- 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?
V&B is more than an architecture documentation method. It also helps the architect identify and record necessary design decisions during development.
Documentation should be the helpful result of making an architecture decision, not a separate step in the architecture process. The more that documentation is treated as a follow-on to design, with its own separate method, the less likely it will be done at all.
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 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).
V&B works in both Agile and traditional development settings. It is notation, language, domain, and technology independent. And it produces documentation that is compliant with Standards ISO/IEC 42010 and IEEE 1471-2000.
Documentation 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, implementers, technical managers, testers, analysts, quality specialists, and others. In short, every member of a software development project can gain.
Fact sheet describing the SEI approach to documentation software architecture that centers on the concept of a view as its fundamental organization principle.
This book provides the most complete and current guidance on how to capture a software architecture in a commonly understandable form.
A Microsoft Word template for a software architecture document is available for free download.
Paul Clements talks about best practices for communicating (documenting) software architectures and summarizes key points from the book Documenting Software Architectures: Views and Beyond and the related two-day course, Documenting Software Architectures
This report compares the Software Engineering Institute's Views and Beyond approach for documenting software architectures with the documentation philosophy embodied in agile software-development methods.
Comparing the SEI's Views and Beyond Approach for Documenting Software Architectures with ANSI-IEEE 1471-2000
This report summarizes the V&B and 1471 approaches to architecture description, and shows how a software architecture document prepared using V&B can be made compliant with 1471.
This technical note proposes a structured approach for reviewing architecture documentation that is centered on the documentation's stakeholders and engages them in a guided manner so as to ensure that the documentation will be ultimately useful to them.