There is no doubt how the architecture is important to shape the solution and define its characteristics in the different architecture domains, and how this solution will be adaptable and dynamic to absorb new business needs and handle different stakeholders’ concerns.
In most architecture development processes, different decisions are taken in the different architecture domains. Architects may make different decisions, such as choosing a specific component, in the conceptual architecture and follow a specific architecture pattern.
However, stakeholders such as developers, business users, and even other architects don’t have the time to go through different architectural views to understand the architecture implications. For example, business users want a clear understanding of the changes that will occur and ensure that the architecture meets their business needs. Other domain architects want a clear understanding of the architecture’s key aspects, including the rationale and alternatives the architect team considered during the envisioning phase.
As an architect, you may face different challenges or business needs which can be achieved by different options or you need to choose a specific pattern or style. As a way to decide that you will have to go through a process and long discussions about why you need to take these decisions and recommend them rather considering other ones.
In this article, I will try to illustrate what is the architecture decisions, their benefits and how to document them.
So, what is the Architecture Decisions?
“In software engineering and software architecture design, architectural decisions(ADs) are design decisions that address architecturally significant requirements; they are perceived as hard to make and/or costly to change.” – Wikipedia
It is called also architecture strategies and tactics.
A description of the set of architectural additions, subtractions and modifications to the software architecture, the rationale, and the design rules, design constraints and additional requirements that (partially) realize one or more requirements on a given architecture – Software Architecture as a Set of Architectural Design Decisions paper by Anton Jansen and Jan Bosch
It is called also architecture strategies and tactics.
“Software architecture is the set of design decisions which, if made incorrectly, may cause your project to be canceled.” -Eoin Woods (SEI 2010)
“we do not view a software architecture as a set of components and connectors, but rather as the composition of a set of architectural design decisions” – Jansen, A., Bosch, J (IEEE Computer Society 2005)
We document the architecture decisions in Architecture decision records or logs, is a technique for capturing important architectural decisions along with their context and consequences.
There are two types of undocumented architecture decisions as mentioned in the Software Architecture Knowledge Management book (2009)
- The design decision is implicit: this can happen mainly because the architect is unaware of the decision, due may be previous experience with a similar situation which makes the architect jump directly to the conclusion.
- The design decision is explicit but undocumented: the architect takes the decision for some reasons and due to the lack of governance they are not documented and there is no traceability why this decision has been taken.
Why are the architecture decisions important?
If architecture is the set of design decisions, then documenting the set of design decisions is required as a way to document the architecture. This is usually not done, though. We can usually get the result of the design decisions, the solutions chosen, but not at the reasoning behind them. Much of the rationale behind the solutions is usually lost forever or resides only in the head of the few people associated with them if they are still around.
- Communicating the architectural change and the decision, we can consider it as a way of thinking to summarize why we needed this decision and why we decided this change to happen and chose this option for it, and also it describes what will be the impact of this change based on the decision has been taken. This is important to another stakeholder, for example, business users, domain architects or developers.
- Close the open questions and the long discussion loops, in the architecture development process we may go through a lot of discussions and brainstorming sessions and actually, we need to communicate the results with other stakeholders. And throughout this process, other stakeholders or even new architects in the different domains will start to suggest or discuss another option may be not compliant with the decision made. In this regard, documenting the architecture decisions will eliminate this cycle and communicate the rationale for the decision to all stakeholders and keep it historical to know how this can be affected by new changes as well.
- It will provide a way of traceability of these decisions as we know why we took them, what are the concerns and business requirements related to these decisions, who are the contributors to these decisions.
- Architecture governance, the decisions logs, and records are used to keep track of these decisions and how they are compliant with the standards we are following.
How can we document the Architecture decision?
In the table below, I think this may be the most used attributes to document the architecture decision, while you can add or remove some complexity as well. There are some extra attributes can be added according to the architecture capability and maturity in the organization, for example, related principles, related artifacts, related decisions, and others you can figure them out 🙂
| ID | A unique identifier for each decision |
| Subject Area | Area of concern, for example, data integrity |
| Decision Statement | Here we write as a statement indicating what the decision is e.g. “Using cloud IaaS”. |
| Status | Decision status, Not Decided or Decided |
| Problem Statement | A short description of the problem. |
| Assumptions | What are the assumptions in the context of the problem? |
| Constraints | What are the constraints in the context of the problem? |
| Motivation | Why this decision is important? |
| Alternatives | A list of alternatives or options we have. |
| Argument / Decision criteria | On which basis, you selected this option or alternative, it mainly includes the criteria of selection, such as ease of implementation, resources availability, expandability …etc. |
| Decision | The decision we decided to have |
| Justification | Why this decision was made and we selected it. |
| Implications | What are the implications we might have after having this decision? |
| Derived requirements | A list of requirements that are generated by this decision. |
| Owner/Major Contributors | The major contributors and owners who took this decision |
Example of architecture decision
It is important to say that using the template is not a decision-making process, it is just documenting them, while you need a decision process and decision matrix to evaluate the best options you need to take.
| ID | AD01 |
| Subject Area | Application structure |
| Decision Statement | The application should be based on Model, View, and Controller (A three tires architecture) |
| Status | Decided |
| Problem Statement | The solution should be maintainable and have separations of layers which will make the application more dynamic for new requirements. |
| Assumptions | The team has proven skills in implementing MVC model. |
| Constraints | None |
| Motivation | The customer asked to have maintainable software, as well to be expandable easily and can use different supporting tools and plugins in the different software layers based on different technologies |
| Alternatives | SOA architecture
Three tiers architecture Client/Server architecture |
| Argument / Decision criteria | Application maintainability
Application adaptability Application expandability Resources capabilities Implementation time |
| Decision | Three tiers architecture will be used. |
| Justification | Based on the customer concerns and criteria has been mentioned, we found that SOA architecture will be costly to be implemented and will need more time to realize the business value which can be obtained quickly by three tires. Moreover, the existing resources are not skilled in SOA architecture. |
| Implications | None |
| Derived requirements | |
| Owner/Major Contributors | Lead Architect, Application Architect, Data Architect, and subject matter experts (Name them) |
You can explore more template using this link
Help to do more!
The content you read is available for free. If you’ve liked any of the articles at this site, please take a second to help us write more and more articles based on real experiences and maintain them for you and others. Your support will make it possible for us.
$10.00
Interesting 🙂 I think the most valuable point for Architectural Design Decisions that it keep the history for the upcoming teams and let them know the rationale of the decision – or irrational 🙂 – this will help more in judging the architecture by knowing behind the scenes
Yes, thank you for your comment Mostafa
Nice article! One thing I would add to the table is ‘other documentation impact’ (which documents were changed/updated based on this decision )
Yes, I agree. Thank you Tarek for your valuable comment