So why do we document a solution architecture in the first place?
We write architectural documentation for a few reasons, the main few being for analysis, implementation and education.
Analysis
In order to improve your architecture going forward, it is important to review what design decisions have been made in the past. Documenting the architecture forms the basis for an architectural evaluation.
Implementation
A good high level architecture will communicate a common message to the teams implementating the system. They can develop in-line with the constraints set out by the architectural decisions and ensure that the system does result in the quality attributes prescribed by the architecture.
Education
When a new developer comes onto a project mid way, it is always a challenge to align them to the existing team and not doing so can lead to the developer going off and doing their own thing, inevitably causing problems. The new developer needs to be educated in the systems high level architecture first, then work his way down the complexity ladder so he (or she) knows what they are dealing with. Not only does the architecture benefit new developers, but it can be used for discussions with key project stakeholders. Since the architectural views are high level abstractions which omit the complexity, non technical stakeholders can review and discuss the system with the architect. These discussions can affect future architectural decisions.
You document to mitigate risk, aid understanding and avoid ambiguity.
When should you document an architecture?
Documentation should be part of design, it should not be a phase that follows design. If you forget to write architecture design decisions down, you might not apply a design decision across the whole project.
How should you document architecture?
Structural Views. Architecture is not a single diagram, it is a collection of perspectives / views of the system.
The documentation should :
- Be sufficiently transparent and easy to understand by new employees
- Be sufficiently concrete enough to be used as a blue print for implementation
- Have enough information present to be used as the basis for analysis
- Be both descriptive (describes what is true) and prescriptive (what should be true, placing constraints on decisions yet to be made)
scottaltham.com 