This page is part of the guide The Practical Software Architecture:
- Software Architecture Issues and Solutions
- The Process Overview
- Documenting Software Architecture
- Vision, Principles, and Constraints
- Preparing the Roadmap
- Decision Making
Table of Contents
This part of the process is the one that will help you make decisions. Note that you don’t need to use this set up for every decision you need to make, but it’s useful to apply this pattern whenever the choice you want to make has an impact on multiple parts of your system and/or multiple teams.
Furthermore, you don’t need to create meetings for each of the steps mentioned below. Depending on the size and importance of the decision, you may want to combine them into a single one. If you prepare well, you can go to a one-hour meeting and explain a given problem, study the alternatives and then make your decision. When you get enough experience, you can even make it in less time. Low-impact decisions can even be made on-the-fly after a short discussion. In any case, if it’s relevant enough, better follow the steps described below in terms of writing down the inputs and outputs.
If your project has several teams, you can also split decision making per team when that makes sense. Especially if the problem is likely to impact only to a part of the project.
👥 Meeting: The Problem Description
First, describe the problem you’re facing: What do you want to solve? It may be a functional or technical challenge, e.g.: design and implementation of a payment workflow, bad performance with database queries, splitting the system into smaller modules, etc.
It’s very important that you also highlight why they are a problem. It might be obvious but sometimes we make the big mistake of classifying as a problem something that really isn’t. A simple, clear reason will suffice when describing the problem, for example: “we want to identify in which part of the flow our users are to target them better”, “we’re wasting at least one hour per day waiting for the database”, “we can’t evolve our code efficiently because it’s too tangled”, etc.
Besides, you need to extract as well what are the specific constraints when looking for a solution. Is it an issue that is extremely urgent so it needs a quick fix? Are there only limited people available to work on that?
Technical Audience and, if the problem is related to functionality, you’ll need Business people to explain it and to be asked if some alternative solutions are valid.
Format and Duration
An hour should be more than enough to start with. When you get better at defining problems you can try to combine this session with the exposition of alternatives and making decisions.
Take into account that a common pitfall in Software Development is investing too little time in the problem analysis and switching too quickly to the search of solutions. Don’t do that: try to understand the problem as best as you can and get all the requirements and constraints. Visualize what are the possible problem scenarios, but at the same time don’t spend too much time in detailing corner cases.
Remember: the best outcome you may get from this meeting is noticing that you don’t need to do anything to solve that problem, or identifying it as not being a problem at all.
During this meeting, use the whiteboard as much as possible. We tend to get distracted when others describe abstract concepts that are easier to understand when are mapped to boxes and arrows. Just use the tools you have. I’ve seen hundreds of lines of useless code written only due to the lack of a good description of the problem.
There should be a Journal Entry with pictures of the whiteboard (if any) and a summary about the problem. And then, it’s time for you and the rest to start thinking about solutions.
👥 Meeting: Alternative Solutions
The problem, described in the Journal Entry. Also, the proposed solutions should be sent in advance by their creators so everybody can have a look and ask questions in advance.
Ideally, the same one that helped to define and scope the problem.
Format and Duration
One hour maximum, try to keep it shorter.
Your main objective here should be to keep things as simple as possible. Remember that Simple is Hard so most probably the fanciest solutions you can think of are not the best ones.
On the other hand, you shouldn’t sacrifice quality in favor of simplicity so don’t confuse a crappy solution with a simple one.
This session should focus on the different available solutions and what would imply to implement them. Each person presenting a solution should cover how it solves the problem without getting into too much detail. Once the overall idea is clear, that person should provide a brief description of what would be the steps (tasks) to get that solution working. By doing this, you avoid putting too much effort into considering solutions that are unfeasible or require too much research.
A list of different alternatives to solve the problem. It might be that there is only one way to solve it, then the decision becomes much easier.
👥 Meeting: Decision Making
The problem description, its constraints and the different alternatives to solve it (outputs from the previous process steps).
Same as involved in the previous steps of defining the problem and alternatives.
Format and Duration
The art of making decisions is difficult but it will become an easy task if you did the previous steps correctly. Knowing your constraints and the available options, it should be possible to identify the best way to move forward.
This session should be limited to 30 minutes maximum but, ideally, it may be combined with the previous one and even with the problem definition when that’s possible. Anyway, you shouldn’t go over one hour when combining these meetings.
Your goal during this meeting is to use all the information available to make a decision and plan the next steps. Try to get a good consensus, although sometimes it won’t be possible. In those cases, people should just understand that not everybody is going to be happy about all the decisions that are made.
Note that you don’t need to choose always the best solution in terms of quality. You may know perfectly that you go for a non-optimal solution but that can be still the best alternative given the constraints and your knowledge at that time. What is important in each case is that you write down why you chose that option.
Use a Journal Entry to document the decision you made and the reasons behind it. If there are remarks in terms of constraints that affected your decision, it’s critical that you write them down too.
Share this decision with the rest of the team and encourage others to respect it and don’t diverge from it. Once you make a decision you shouldn’t be reconsidering it or discussing it all the time: that’s very frustrating, especially when you dedicated a lot of effort to analyze all the possible options.
The better you become at using this process, the better your Decision-Making mechanism will be. When people get used to how decisions are made, they’ll know what is the time to propose new ideas or argue about specific alternatives, and when is time to just accept the decision no matter if they don’t think that’s the best option.
Even though the decisions should be respected and followed for a while, you can always revisit these decisions when new information is available or constraints change. But the change should be always backed up by a good plan.
Continue reading this guide: Practical Software Architecture – Conclusions