Engineering decisions
Software engineering decisions often need to be taken in any project. They can vary in impact, importance and risk, and they can be very broad and fundamental to very specific and less relevant.
How to decide
The techniques and the amount of effort spent on the decision should take into account the impact, importance and the risk of the decision.
It is important to understand the impact of the decision in order to invest the proper amount of time and effort on it. Usually decisions are classified in three different types:
-
Strategic/Extensive: represents high impact/risk in the project. These decisions represent a higher risk for the project, and when making a bad decision, the consequences and impact are major. In a software project, they can be the programming language, the database, runtime environment, high-level architecture, and so on. Consider spent more time on this kind of decision by engaging specialists, doing prototypes, POC (Proof of concept), and any kind of research.
-
Tactical/Limited: their impact and risk are medium, but still can have a considerable impact on the project. Examples: frameworks to adopt, libraries, data formats, smaller architecture decisions, etc. Depending on the decision, prototypes and research can be used, but avoid spending too much time on it.
-
Operational/Routine: very commonly teams need to decide on smaller topics, like contracts, code standards, messages, and many more. These decisions represents a small impact and risk for the project and tend to happen frequently. So do not spend much time on it.
Steps for the decision making process
Depending on the type of the decision, the steps below can be used to plan, execute and document the decision. Although some steps may not be needed for small and/or quick decisions.
- Identify what should be decided.
- Evaluate the impact and risk of the decision.
- Determine how the decision will be made.
- Generate a list of options and/or possible solutions.
- Execute the research, decide directly, or postpone the decision.
- Execution: select the best solution.
- Document and communicate your decision.
Pitfall 1 on making decisions: Avoid premature decisions
Performing decisions too early or without the proper inputs can lead to suboptimal decisions and rework. Several industry principles state the importance of not adding capabilities and functionalities to the software until deemed necessary. For example:
- YAGNI (You aren’t gonna need it): YAGNI is a principle behind the XP (Extreme Programming) practice of “do the simplest thing that could possibly work”. The idea is to avoid building presumptive features that may not be needed in the future. [1]
- KISS (keep it simple, stupid): is a design principle noted by the U.S. Navy in 1960 which states that most systems work best if they are kept simple rather than made complicated; therefore, simplicity should be a key goal in design, and unnecessary complexity should be avoided. [2]
The same applies to decisions. Avoid premature decisions based on assumptions or hypotheses. If something can be decided later, consider deferring the decision when it’s confirmed that is needed and when there’s more data available.
Pitfall 2 on making decisions: Get stuck or delay decisions
Another pitfall when making decision is when there are too many options, or the investigation phase is not making progress due to endless discussions, research points, different opinions, or the avoidance/fear for making the final call prevents the decision to be made.
The Analysis Paralysis, or Paralysis by Analysis, states this problem. Here are some tips that could help [3]:
- Define a deadline to perform the decision.
- Ask for help or share the decision with the team.
- Define boundaries on what needs to be known now and what can be discovered/learned later.
- Breakdown into smaller decisions or checkpoints.
How to document
Decisions need to be documented due to several reasons: people might miss the information after some time, new members joining the project, a similar problem may arise in the future, and so on.
At APG, there are many tools and formats used for this, you should use the tools in place in your team or project. In terms of format, a recommend format for engineering decisions is ADR (Architecture decision record) [4].
ADRs are a simple template meant to register technical decisions. They can be stored along with the code repositories and can be versioned, making them easy to find and maintain. One of the key aspects of ADRs is to provide more context over a decision, what were the options considered, and also its consequences.
This is extremely helpful to address questions after a decision is made, or new people join the team and wonder why something was done that way or whether alternative options were considered back then.
How to communicate
Every decision needs to be communicated. At APG, we prefer over communication instead of not reaching all the interested parts.
So, use tools and channels available in your team and project for that. Consider broader channels for strategic/extensive decisions and limited channels for the operational ones.
If the decision is documented at some particular tool, prefer to share a link for it, but make sure the information is accessible for the audience.
Techniques to perform the decision and solve conflicts
When a decision needs to be made, there could be different opinions among the persons involved in the process. When there are more people or more than one team involved, things can be more complicated, resulting in a long time to agree on a decision, conflicts, and endless discussions.
Situations like these can delay projects, harm relationships, and increase tension and friction within the teams.
To avoid situations like these, APG has recommended methods and approaches that can be used to help in the decision-making process. These methods can be applied in multiple contexts, but they also should be used when a technical decision needs to be made.
Such methods are:
- RAPID: The model splits the responsibility into 5 roles: Recommend, Agree, Perform, Input, and Decide. The Decider role has the D (Decision), and all the other roles support the process. [5]
- Karpman drama triangle: The Karpman drama triangle is a social model of human interaction proposed by Stephen B. Karpman. The triangle maps a type of destructive interaction that can occur among people in conflict. [6]
It is important to mention that not all decisions require a formal decision-making model, like the examples above. Consider using them only when necessary, for strategic decisions and/or when there are multiple teams/departments involved.
In general, good communication principles also apply here, i.e.: active listening to other opinions, looking and understanding other perspectives, reflect on your own contribution to the problem, etc.
When there are too many people trying to reach an agreement, involving only people that are directly impacted can help to focus the discussion.
Also, getting external and impartial input from someone that is not directly involved can help. For this, we can request help from experts in the company (Guilds) and some external specialists like AWS support.
References
[1] Yagni
[2] KISS principle
[3] How To Overcome The ‘Analysis Paralysis’ Of Decision-Making
[4] Architecture decision record (ADR)