Software architecture document guidelines
Include information that is complementary to the code
Please see the Software Architecture for Developers book for the most up to date version of these guidelines.
The purpose of the software architecture document (SAD) is to provide information that is complementary to the code. At a high level, this might include:
- An outline description of the software architecture, including major software components and their interactions.
- A common understanding of the drivers (requirements, constraints and principles) that influence the architecture.
- A description of the hardware and software platforms on which the system is built and deployed.
- Explicit justification of how the architecture satisfies the drivers.
See The code doesn't tell the whole story for the rationale on why software architecture documentation is necessary. As a guiding principle; the software architecture document should contain information that is complementary to the code and describe what the code itself doesn’t.
The following sections illustrate the content that should be included in a software architecture document and present information from several different views to take the most common stakeholders into account. It's worth noting that all of these views aren't necessarily required when taking into account factors such as project size, complexity, requirements, team, etc. If the information is available elsewhere, the software architecture document should make a reference to that source rather than repeating it (e.g. non-functional requirements may be stated in the requirements documentation and designs may be in separate design documents or a UML model). The SAD is a living document and may not contain all of the information listed here at any point in time.
