Decision records, tool which made me more productive over the years

Too many options

Software industry is filled with lot of options to solve any problem. This was not the case 15 years back when I started career. Mostly we will hear about 2–3 programming languages and someone at tech executive level will make the decisions on which one to use. Same was the case with databases and other tools. These decisions were also driven by enterprise contracts and license costs with tech providers like Microsoft and oracle.

Hence architectural options were also limited based on underlying tech.

In last 8 years industry has gone through big revolution due to increase in programming languages, open source tools and various ways to learn new tech. Decisions are no more confined at executive level. In my experience for past 6–7 years only decisions which tech executive takes is about cloud providers or in house infra. Rest of the tech decisions are owned by development teams.

With great power come great responsibility

So teams have to make sure to evaluate all the possible options and take a informed call to select architecture, design or any framework.

In last 8 years I have been involved in more than 5 projects which started from scratch and this gave me opportunity for tech exploration and decision making. For few projects I were involved in making informed decision but when I moved on from project, no one knows why these decisions were take and sometime after 6 months even I forgot about trade offs of certain decisions and what all we evaluated already.

Almost 4 years ago I was introduced to Architecture decision record aka ADR. Like other coders I also hate documentation and as per me code is the best document, but one thing which code does not tell how did we arrive to this decision, what all options did we evaluate and trade off for all the options.

Thats where architecture decision record helps, to recollect how did you arrive on certain decisions. Now I use this as extended practices to capture HLD, LLD and any important decisions which required multiple options to be evaluated. So instead of calling it ADR tool for me its decision records aka DR.

Decisions records are very useful in following ways:

• Sharing decisions with wider group and multiple stakeholders. If you have documented every options considered with pros, cons, data points and spike outcomes, it becomes easier to communicate the decisions and making meetings more effective.
• Can be passed for offline reviews to save time during meetings.
• In decision records as all the options given by others are documented with data points, helps in making informed decisions based on facts rather than egos and emotions. At the same time people feel good that their options were considered rather than ignored.
• In the future is decision needs to be evaluated, this become a good starting point.
• Can be used as onboarding document as it will capture problem statements and any specific rerquirement.

If you can use decision records in any other way, do write in comments.

Outline for ADR

• Name should clearly reflect what the decision is about and version number depending on which tool is being used to capture DRs.
• Problem statement
• Considerations to solve the problem, like expected load to support, latency requirement and other cross functional requirement.
• Options considered along with pros, cons.
• Outcome of any POC if done. Also include code links if present.
• Preferred options and why
• Who all participated in decision making
• Version, and link of previous versions.
• Design references, if putting design images please provide design tool links as well so future revision become easier.

When to consider or not to consider

Consider

• Architecture level decisions
• If problem can be solved at multiple ways using different tools and framework
• If multiple POCs are being done to finalise the decisions
• Many stakeholders are involved in making decisions.
• Decisions regarding integrations across teams
• If decisions needs to be shared multiple time with different groups, documenting it once can save lot of time during discussions.
• Database level decisions

Don’t consider

• Easy to make decision and one person decision, something which is within programming language
• Not very crucial decision and easy to change if better options are found later.
• Very small code level details, please don’t write decision records as

Tools for capturing decision records

• Maintaining along with codebase. Easy to maintain versions as well. It has one disadvantage, not everyone might have access to codebase repo. With this option sending ADR for review, capturing and maintaining comments for future become difficult. Its a good option if there are decisions around low level design.
• Confluence or similar tools: Find this better options better for reviews, capturing feedbacks, comments and offline discussions as well.

One rule I follow to consider decision records, if a decision is taking multiple days and I have started making notes for it, I would like to capture thoughts and work done for it in a decision record. This helps me to recollect all the work which I did during decision making and revise the decision faster if needed any time in future.