As architects, we continuously make decisions. But not all those decisions are made equal. Only those considered as architecture decisions are under our responsibility as architects and should be carefully analyzed and documented.
But how to identify these architecture decisions and why they are important?
According to Michael Nygard: “Architecturally significant decisions are those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques”. The architecture decisions have a deep impact on the system we are building (impact the structure of your system) and therefore you need to document them.
How to document the architecture decisions?
You need first to gather enough relevant information (business and technical) to justify the decision you are making.
One of the most interesting approaches to document architecture decisions is through the use of the Architecture Decision Records (ADRs). An ADR consists of a document (usually one to two pages) describing a specific architecture decision. The ADRs can be written using plain text, word documents or using a wiki or a confluence page.
A sample of the ADR can be found here.
Make sure to communicate the decisions you make to the stakeholders (other architects, team leads, developers ..etc.). The next time your team will discuss again these decisions, refer them to your ADRs so the discussions will be, hopefully, shorter and more efficient.
References:
Michael Nygard – Documenting Architecture Decisions.