Artifact: Architecture Notebook |  |
This artifact describes the rationale, assumptions, explanations and implications of the decisions that were made in forming the architecture.
Domains: Architecture
Purpose
To capture and make architectural decisions, and explain those decisions to developers.
Relationships
Fulfilled Slots | [Technical Architecture]
Roles | Responsible: Architect | Modified By: Architect
Tasks | Input To: Refine the Architecture Outline the Architecture Design the Solution Plan Iteration | Output From: Outline the Architecture Refine the Architecture
Description
Main Description | This artifact describes the Software Architecture. It provides a place for maintaining the list of architectural issues, along with the associated architectural decisions, designs, patterns, code documented (or pointed at),etc. all at appropriate level to make it easy to understand what architectural decisions have been made, and are still left to be made. Architects should use this artifact to collaborate with other team members in developing the architecture, and to help team members understand the motivations behind architectural decisions so those decisions can be robustly implemented. For example, the architect may place constraints on how data is packaged and communicated between different parts of the system. This may appear to be a burden, but the justification in the Architecture Notebook can explain that there is a significant performance bottleneck when communicating with a legacy system. The rest of the system must adapt to this bottleneck by following a specific data packaging scheme. This artifact should also inform the team members how the system is partitioned or organized so the team can adapt itself to the needs of the system. It also gives whoever must maintain and change the architecture later their first glimpse of the system and its technical motivations.
Brief Outline | At a minimum, this artifact should: List guidance, decisions and constraints to be followed Justify those guidelines, decisions and constraints Describe the Architectural Mechanisms and where they should be applied. Team members who were not involved in those architectural decisions need to understand the reasoning behind the context of the architecture so they can best address the needs of the system. Consider adding more information when appropriate. A small project shouldn't spend a lot of time documenting the architecture, but all critical elements of the system must be communicated to current and future team members. Useful content includes: Goals and philosophy of the architecture Architectural assumptions and dependencies References to architecturally significant requirements References to architecturally significant design elements Critical system interfaces Packaging instructions for subsystems and components Layers and critical subsystems Key abstractions Key scenarios that describe critical behaviour of the system
Illustrations
Templates | Architecture Notebook
Tailoring
Impact of not having | Without this artifact there will be no coordination of the individual design efforts and it will be difficult to establish and communicate an overall architectural vision for the project.
Reasons for not needing | This artifact is not required if an existing reference architecture is being used or another approach or set of artifacts are being used to document the architecture. This artifact may not be needed if the design is relatively straightforward and does not have any architecturally significant risks.
Representation Options | A set of architecture models could be developed as part of the architectural documentation. For more information, see Guideline: Modeling the Architecture.
More Information
Checklists | Architecture Notebook
Concepts | Software Architecture
Guidelines | Modeling the Architecture
This program and the accompanying materials are made available under the Eclipse Public License v1.0 which accompanies this distribution. OpenUP Copyright.