What is a Decision Record?
A decision record (DR) is a document that captures an important decision made (along with its context and consequences) in such a way that allows transparency into the decision making process. Context surrounding the problem, considered options for the final decision, and pros / cons of said options are all important aspects of DRs. Lastly, DRs are used in a Git / GitHub setting, where changes to each decision are inherently stored and updates to decisions can be proposed in a familiar manner.
Decision records can come from anywhere, but working groups present a great opportunity for the creation of decisions that benefit from the format of a DR. Keep in mind that these decision records aren’t a replacement for collaboration, but rather an output of a team working together to make a decision.
How do I utilize Decision Records?
DRs are meant to be communal documentation, which means anyone in the organization can reference, modify, or create said DRs. The organization and naming of the DRs is towards discoverability and searchability by those without prior context. Hopefully you can find a decision related to whatever you have a question on. If not, please make any changes you deem necessary to help facilitate further searches (or create a new DR if none exist for your question!).
These DRs can and should be used to help guide new development, any refactors and / or updates to existing efforts.
How do I read a Decision Record?
The DR contains:
What is the decision about
The first section details the context of the problem. What question needs answering? Why does this decision record need to exist? Is there context around the problem that this decision will help address?
What the agreed upon decision is (if any)
The second portion of the DR gives a simple identifier of the option that was chosen as the decision, along with any supporting arguments as to why that was the chosen option. This should be taken as the go forward strategy for any new work and changes to existing work. It does not imply, though, that this decision is reflected 100% throughout the system, since perpetuating a decision can range from a simple modification all the way to astronomically large refactors.
What were the considered options
The last section of the DR addresses what options were considered. This is to transparently detail what was on the table and what was not even considered (which may be equally as important). Any additional information about each considered option is listed here, as long as the list of pros and cons. This list’s goal is to construct a picture of the context that will help the reader understand the arguments that went into the decision.
It’s important to note how these considered options are referenced. Each item listed under the Considered Options section is the identifier for that particular option, and should be used as such when referencing that option elsewhere. This reference is in the form of a very short (1-5 word) description of the option. It is not intended to give context, but rather readily identify and differentiate the option from other options.
How do I modify an existing Decision?
If you are looking to propose an update to an existing decision because of new information or available options, you are welcome to add the relevant information to the existing decision record and modify the chosen option. Since we live in a version control world, there is no need to create a new Decision Record to reflect the new decision. It is better to keep new information next to the old information and a commit history showing the changes, than have this information scattered over a myriad of various Decision Records of different ages.
How do I write a new Decision Record?
If you are in the market for a new decision record, there is a template located under the base directory. This should give some basic guidance towards constructing your own Decision Record. Copy this template and modify the contents to reflect the decision you wish to propose. There are certain sections that are optional, or have optional elements. Add supporting documentation as needed, but keep in mind that nobody has ever questioned a decision because there was too much documentation. The more context you can provide, the easier it will be for someone to read the Decision Record and understand the thoughts that went into the chosen decision (even if that someone is you, 1 year from now).
How do I reach a decision?
There are many times where you are writing a Decision Record, but do not yet know what the decision will be. In these scenarios, it is best to put TBD for the Chosen Option. Clearly marking something as not yet having a decision is much more useful than misrepresenting what the decision is.
Utilizing GitHub pull requests is a great way to garner feedback and votes towards a decision. Opening a pull request with a Decision Record filled with context and ideas, but with a TBD Chosen Option allows a non-biased way to stir conversation towards a decision. There may be situations where a temporary slack channel may be made to help consolidate discussions on the decision. If this is done, it is paramount that this channel is linked in the PR such that other / future readers can follow the decision path. If a video call or in-person meeting happens to discuss the decision, it is incredibly important to take as many notes as possible and accurately reflect those in the Decision Record.
Generally, the best way to vote for a decision is to add a comment on the pull request highlighting the chosen option you vote for.
Decision Record best practices
There are some best practices for writing / modifying a Decision Record that help keep things as comprehensible as possible.
- Don’t assume the reader will reach the same decision as you given the data. If there is a reason for a particular decision, state as such so other readers understand why you chose that option.
- Make sure the contents of the Decision Record is presented in present tense and free of outside bias or context. This makes the DR relatable at all points in time, not just when the decision is made.
- Try to keep DRs as focused as possible. If there is the ability to separate a large decision into multiple smaller decisions, it is advised to do so. This keeps each DR more readily consumable and relatable. When a DR is made of numerous smaller decisions, the permutations of the available options bloats the DR into an unreadable mess.
- Avoid introducing bias into the DR as much as possible. Everyone has biases, but it’s important that these aren’t forced unfairly on to others.
- Capture as much extra information you can related to the decision into the DR. The goal is that the DR is self-contained for a particular decision, allowing easy digestion by the reader.