Solution Architecture Decisions: The Foundation of Solution Architecture

Dan Hughes
January 22, 2023
People gathered around making a solution architecture decision

I have discussed decision-making topics like evaluating technology solution options and solution options analysis in prior articles, so today was going to focus on solution architecture decisions. Any solution architecture is the result of a series of decisions, so they are an essential element of solution architecture design. I am not going to focus on the decision-making process but on when and how to document a solution architecture decision. However, you can check out my previous article on making better technology decisions for some guidance on decision-making.

In the Wittij People-Centric Architecture method, we have a specific set of diagrams and structured information that a solution architect should produce when designing and documenting a solution architecture. We developed the method to optimize clear communication of solution architecture designs: fewer words but more information. As a result, many decisions will be evident through the core design elements of the architecture. But there will be times when it is prudent to document a decision.

When to Document Solution Architecture Decisions

When should you document a solution architecture decision? The default answer to this question is *never*. Per my previous comment about fewer words, you should only record an architecture decision if it is absolutely necessary to do so. We have three triggers for determining when to document a decision.

Triggers for Documenting a
Solution Architecture Decision

It is unclear why it was made

It is a controversial decision

It is a bad decision

It is unclear why it was made

Anytime you make a solution architecture decision that aligns with the organization's documented or de facto standards or is the standard or best practice approach, nobody's going to blink twice when they see that in your architecture. It's the expected decision. On the other hand, if people are going to wonder why you made the architectural choice you made, you are better off confirming with a decision and providing some supporting analysis. You can also use decisions to capture details foundational for the architecture but too low-level to surface in the logical-level design information appropriate for a solution architecture design to drive some clarity. However, tread lightly and remember that less is more.

It is a controversial decision

Sometimes you face a decision that is "controversial." People disagree on the preferred direction, so you must analyze options and drive discussions to reach a consensus. Boy, that is exhausting, and it would be even more exhausting if you had to do it all over again in 6 months because nobody remembered why you landed where you landed. This category of decisions is often the result of an options analysis. However, some don't need the rigor of formal analysis, but still require some debate. In either case, you will want to capture the analysis and the outcome.

It is a bad decision

What? Why would you want to make a bad decision? The answer is that you would not want to, but sometimes you have no choice. Often, solution architects analyze and facilitate their way to the best decision for the organization, but are still unable to lock it down as the agreed upon direction for the implementation due to factors outside their control. The most typical factors are increased cost, elongated delivery timeline, or functionality gaps in the underlying components within the architecture, but there can be others.

Documenting these bad decisions highlights for everyone that a bad decision is being made and also creates a thread to pull at later when the a solution architect designs the next version of the solution architecture. Any time a solution architect documents bad decisions, they should also be adding risks to the solution architecture risk register. If you can't identify any risks to associate with the bad decision, you need to ask yourself if it is truly a bad decision.

How to Document Solution Architecture Decisions

So now that I covered the "when," let's talk about the how. As mentioned above, we minimize the design document narrative in our People-Centric Architecture method. We propose a simple, structured table to capture a decision because it helps you keep your narrative tight and makes it easy to follow the decisions in your document.

DECISIONThe decision goes here.
ANALYSISA summary of the analysis that led to the decision.
TARGET[Optional] Identifies the correct decision if this decision table captures a bad decision.
FACTORS[Optional] Provides the factors resulting in this decision if this decision table is documenting a bad decision.


The first and most important thing to capture in your decision block is the decision! The decision should be a complete sentence and stated as an assertion. It should also be comprehensive so that someone can read only the decision statement and not have to look at any other details you capture in the decision table to understand the decision. It should also only make a single assertion. If the outcome of your analysis resulted in multiple impacts on the architecture, then they should be documented as separate decisions. Be on the lookout for "and" in a decision statement.


This is a brief summary of the logic that led to this decision. It may provide the reasoning supporting this decision or a light options analysis. Documenting inline works for decisions that did require the rigor of a more comprehensive evaluation activity. For those larger evaluation activities, you can link to an external document that contains the analysis, like an options analysis or proof of concept exercise that was used to drive the decision.

That's it for most decisions. However, for the final category of decisions I mentioned above, where the architect is making a bad decision, two additional pieces of information are important to capture.


If you are documenting a bad decision, this is where you put what the better decision would have been. You should state the target using the same approach as the decision field. In cases where you haven't yet determined the target, you can put "to be determined" instead.


Here is where you document why you are making a bad decision. Why are you making the decision you are making and not just going with the "target" decision?

Using that table structure, here is an example of a decision:

DECISIONUser credentials for HackMe will be managed locally in the HackMe database.
ANALYSISProof of Concept (see document here) failed to successfully connect HackMe to ActiveDirectory
TARGETUser credentials will be managed in ActiveDirectory.
FACTORSHackMe is the only product that can fill this business need and does not currently integrate with Active Directory.

So that's it: solution architecture decisions in a nutshell. Here are some closing tips:

  • Only capture solution architecture decisions when absolutely necessary.
  • Keep the decision narrative as concise as possible.
  • Ensure you capture the risks associated with the decisions in your risk register.

The final thing that sometimes arises when discussing decisions is "now what?" What is the value of the decisions documented for the solution architecture? Capturing decisions brings value by:

  1. Helping you drive the right conversations to ensure all decisions are being made with the right level of rigor.
  2. Demonstrating that analysis and diligence went into the design.
  3. Communicating the architecture clearly to all its consumers.
  4. Informing future architects (or future you) why you made the decisions and which they could improve upon.
Dan is the founder of Wittij Consulting. Prior to founding Wittij, he spent a decade in software development before moving into IT architecture, where he created an Open Group recognized architecture method and led delivery of all services for a company specializing in enterprise and solution architecture for 15 years. He is an energetic, thoughtful leader with an ability to engage and motivate people, and has been called a “force multiplier” for his ability to not only deliver great value, but also increase the value and capability of the people around him. Dan is a strong facilitator, able to understand and resolve complex disagreements with diplomacy. He comprehends and communicates clearly both at the detail level and the boardroom summary level to both business and technical audiences. His knowledge of enterprise techniques and technologies is broad and deep, and includes industry expertise in manufacturing, financial services, banking, health care, insurance, regulatory compliance, and NGOs.
Copyright © 2024 Wittij Inc.
crossmenu linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram