Solution Architecture Decisions: The Foundation of Solution Architecture

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.

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.

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.

Analysis

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.

Target

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.

Factors

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:

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.