Last updated on March 4th, 2023 at 03:44 pm

Architectural decision making is a core responsibility of software architects.— Philippe Kruchten

As an architect, an important part of your work is making architectural decisions that will impact the projects you are working on. According to Michael Nygard: “Architecturally significant decisions are those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques”.  

The decisions are never easy to make and need to be carefully analyzed. Consider making architecture decisions as a process: first, gather enough relevant information, make a decision backed by rational justifications, review and refine it with your colleagues and stakeholders, document all concisely and clearly, and then reiterate until you get to a satisfying decision. The following are some considerations to help you in making your decision process:

– Trade-offs

Justifications and trade-offs as the building block of the decision-making process. If you don’t find yourself thinking about the trade-offs of the solution you are proposing, it is probably a sign that you are missing something important. The trade-offs are what will justify and back your decision. You need to be able to state why you have decided, for example, to use Microservices architecture instead of the Monolith, and explain the trade-offs of your decision. All decisions involve trade-offs.

– Feedbacks

Your teammates’ feedbacks are valuable to improve the quality of your decisions. To have them collaborate, prepare your presentation or your document that illustrates your decision. Start by stating the problem, and don’t assume that your teammates already know the details of the problem. Then, dive from the high level to the details explaining your decision and the trade-offs justifying your solution. When listening to the comments, seek particularly for arguments and trade-offs if they are proposing improvements or alternatives. 

– Time

Start thinking about your problem, options, and trade-offs early in the project. You will need more time than you expect to analyze those trade-offs to determine the best solution. Your thinking will evolve and even change from one decision to another when you gather more information and have feedback from your colleagues and the stakeholders. 

It is better if you can delay your decision at the last responsible moment; a lean development principle defined as: “A strategy of not making a premature decision but instead delaying commitment and keeping important and irreversible decisions open until the cost of not making a decision becomes greater than the cost of making a decision”. But at the same time, avoiding necessary decisions can even be worse than making the wrong decisions.

– Documentation 

Start documenting your decision as early as you consider the different options and the trade-offs. Documenting your options and ideas during the decision process will help you think deeply about your solution, the trade-offs, and the justifications for your decision when you write down your document. 

The architecture decisions are usually documented in Architecture Decision Records (ADR). The ADRs can be written using plain text, word documents, or a wiki or a confluence page.

An ADR has a title, a status, and a version. You start by documenting the context and why you must make this decision. Then in the next section, you present the options, the trade-offs, and your decision. What is critical here is to clearly explain why you made this decision. And finally, you document what will be the consequences of this decision on your team, your project …etc.

You can find an example of an ADR here.

About the Author

My name is Adel Ghlamallah and I’m an architect and a java developer.

View Articles