One problem area that I have seen while consulting to different software engineering teams is the lack of documentation and tracking when it comes to important technical decisions.
Organization after organization, I kept hearing the same complaint of teams not knowing why key technical decisions were made this way or the other.
Typically, the mysterious origins of these decisions were to be found in whiteboard sessions that were never documented. Sometimes, these could also be the result of individual or group efforts that resulted in a decision, which, again, was not documented anywhere.
The problem this lack of transparency and tracking poses is that when key decisions are made, these typically have long lasting implications for technology and business alike. Months and years down the line, people wonder why a certain decision was made and come up with nothing.
When you can't pinpoint why a certain decision was made and in what context, you cannot easily pivot from that decision as you are never too sure what doing so will affect.
Moreover, when a decision poses to be problematic or just plain wrong, it cannot be easily rectified, because, again, you just don't know what would be the implications of doing so.
This often affects costs in terms of both direct cost and lost opportunity, and this continues in perpetuity for as long as that original decision is followed.
Let's bring this home with a concrete example. In the past, I have come across a number of teams who have selected a particular cloud vendor and when I came in, they were at a point where they were unhappy with the choice that was made. The problem, you guessed it, was that the rationale behind choosing a cloud vendor vs another was not documented. The result was that these teams, although not too far along their cloud journey, struggled to make a switch to another vendor because they did not know the justification for the original decision and what it could impact.
The great news is that the solution here is simple.
Document your technical decisions.
This does not mean that you need to document every little thing. What it does mean though is that you should be documenting those decisions that affect your systems in an important or long-term way.
Most architectural decisions fall under that category as architectural decisions, by their very definition, impact a system or multiple systems in an overarching manner.
One very popular way to standardize and streamline the documentation of such decisions is using ADRs - Architecture Decision Records.
Using an ADR allows a team to create a snapshot that captures all the key information for why a specific decision was made, when it was made, what were the tradeoffs, and what did the approval process look like. There are a number of popular templates and one that I personally have used over the years is the one from Michael Nygard - https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md
The template looks as follows (copied from the Github repository above)
Title
Status
What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?
Context
What is the issue that we're seeing that is motivating this decision or change?
Decision
What is the change that we're proposing and/or doing?
Consequences
What becomes easier or more difficult to do because of this change?
That's it!
It does not require a twenty-page document to capture why you are making an architectural decision. All it takes are a few key pieces of information and storing this data in an organized way within your regular documentation repository.
The effort for this is minimal. Yet, the gain can be immense.
Comments