Technical decisions are made all of the time and whatever process you currently have in place for making and communicating decisions probably seems sufficient. Most of the focus goes to the decision being made but in our experience, less attention is given to how the decision was made as well as capturing context and rationale. Technical Decision Records address that gap.

Why do we need TDRs?

We have led software development teams from multiple organizations and saw that there was a pattern of decision making that wasn't transparent, collaborative, or well recorded. This meant that decisions were either poorly understood or time was lost when later they were questioned. The same rigor that was being applied to software development was not being consistently applied to the foundational decision making supporting software solutions.

Even without TDRs, there are a lot of good decisions made, but team members and stakeholders may still be left scratching their heads on the rationale or questioning if another option would have been even better - cheaper? faster? more extensible? Furthermore, if you're planning a software product that will outlive your involvement, you might be judged by these decisions for years to come.

So one day when we got the opportunity to work together on a project, we set out from day one with a TDR template and vowed to use it for all of our key technical decisions. We scaled the format based on the gravity of the decision, keeping the process lightweight and decisions moving. When it was time to off-board and transition the product to a new team, these records built a trust and understanding that underpinned the successful transition.

We are now staunch supporters of TDRs and have used them across a variety of software solutions and teams. Stakeholders appreciate the transparency and collaboration. Development teams enjoy the context for decisions. And maybe most importantly, decisions are made with timely confidence.

<aside> 🚨 "Wait, our organization is very lean. This will slow things down"

This is a common objection to just about any addition of process or documentation. In general we agree, but for TDRs we have found this to be a myth for several reasons:

  1. You can adapt the TDR template to your level of need to keep it from being an unnecessary burden.
  2. TIme spent aligning stakeholders and teams on decisions is reduced, often with more time saved than spent.
  3. Bad decisions ultimately consume more time than good decisions. If you make one or two better decisions because of TDRs, your organization is likely ahead.
  4. TDRs encourage decisions to be made instead of sitting in limbo. Making an interim decision and re-evaluating later is common and supported.

</aside>

What is a TDR?

A technical decision record (TDR) is a short piece of documentation that captures the decision making context, reasoning, and result of a technical decision. The TDR format presented is intentionally lightweight and avoids being overly formal. While it could certainly be used as a versioned document in a document management system, we suggest developing TDRs in a wiki, code repository, or anywhere else that your team collaborates.

The format proposed should be seen as a starting point. It includes the various areas we have found to be important across multiple teams and solutions. However, you are encouraged to adapt it to your needs. It is a good idea to have consistency in format between your TDRs so once you settle on your preferred format, create a template that can be used to jumpstart new decisions. See our templates at the end of the book for help.

Using this Book

The first thing to note is that this book covers TDRs from two angles:

  1. An overview of the TDR format. Each chapter represents a section of the TDR format with suggestions on how to approach the section.
  2. A sample TDR for an Identity Provider (IdP) Solution. This is intended to give you insight into how we develop a TDR but it also contains useful information if selecting an IdP is your goal.

If your goal is to understand TDRs and think about how they could be used in your organization, you may want to focus on the first part of each chapter and skim the IdP details for inspiration.

If selecting an Identity Provider is your goal, we obviously recommend building out a TDR and you will find a lot of content in this book to help you get started.

If however, you are looking for an academic discussion on decision making, scoring algorithms, or detailed technical guidance, those are all discussions for another book.

Every chapter of the book follows the format: