Decision Archeology: Using ADRs with Existing Products

I've had the same question from a few people lately. They've seen how Architecture Decision Records (ADRs), and other Business Decision Records, improve their software architecture and development process, but they wonder what to do about the decisions made before they started using ADRs. Should you create ADRs for historical decisions?

The answer is most definitely yes. The benefits outweigh the effort. Get stuck in with the following advice:

The benefits of recording historical ADRs

You may find that some historical decisions now need to be reviewed to get the best solution to the problem you are solving.

The benefits are overall the same as for creating any ADR, but with a few additions:

• You are filling in the gaps in your architecture decision knowledge and therefore will see the benefits of having ADRs more often (such as being able to point to an ADR to answer a question).
• You get the benefit of reviewing that decision with all the new information that you have today. You may find that some historical decisions now need to be reviewed to get the best solution to the problem you are solving.
• Where you have done the work of investigating a historical decision you now get to record all your hard work for future-you and others to benefit from. Your effort was not for nothing, and next time your work will show up in search results and you won't have to repeat the investigation.

For those new to the benefits of ADRs here are the main ones:

• You avoid accidentally changing decisions that were made for a very good reason, and wasting time and money on investigation and implementation of a new decision that will negatively impact your solution.
• They are quick answers to questions that keep popping up or when onboarding a new team member. Current team members do not have to spend time explaining (if they know the reason the decision was made at all) and time isn't wasted looking into the decision.
• You don't need to worry about people leaving the company and taking key decision information with them. It is all recorded (and, of course, you have a backup strategy, don't you?).
• ADRs can be used to facilitate the decision-making process, enabling multiple people to contribute to the decision asynchronously (or synchronously if you'd prefer).

Use existing information

Even if the documentation for your product is not comprehensive you very likely have some information that you can piece together to generate your historical ADR. When looking at documentation remember that it may have been updated since a decision was originally made. You can also look at repository commit messages which may indicate process and help you find the decision's history.

Good places to look for decision criteria (what the options were possibly scored against) are requirements documents, constraints, and architecture characteristics / non-functional requirements (NFRs). If you were creating an ADR for a new decision these are the sorts of things that you would rate options against. User stories, spikes and meeting minutes may hold other clues. Remember that the criteria you identify may not have been used in the original decision. If you ever decide the historical decision needs review the decision factors you have discovered can act as a basis for your new decision (with any new information added).

It is not compulsory to record options, but if you can accurately see what they were it is worthwhile¹. When attempting to work out what the options considered might have been you may need to do some detective work, especially if more than a couple of years have gone by since the original decision. For example, if the decision involved styles of architecture or how services should be communicating, the options available at the time might be very different to the options available now². Serverless may not have existed. Event-driven distributed architectures may not have been on anyone's radar. Don't accidentally add impossible options to your historical ADR. Stick to facts.

Discover together

You will find that information is spread across a team working on a product, so get input from as many people as you can

If you have already done some digging to discover why a historical decision was made you already have the basis for creating an ADR for that decision. If you haven't yet done that work (or don't feel it is comprehensive), you don't need to complete it all in one go. Think agilely and iterate over the decision record as you find more information.

It is likely that you are not working alone. You may not have even been working on a product when a historical decision was made. Creating a historical ADR should be a collaborative effort. You will find that information is spread across a team working on a product, so get input from as many people as you can (even if it is only sign-off on your assumptions).

Declare assumptions

Speaking of assumptions, it is unlikely you are going to be able to find all the information that you would like to include in your historical ADR. As with any documentation, you must include any assumptions that you have made (maybe you have assumed that on-prem solutions were discounted due to a company policy, or that a particular architecture characteristic was important in making the decision).

Assumptions should be put in front of others in your team to get their input. They may be able to confirm or reject your assumptions, or add more information.

Highlight what isn't there

It is important that anyone reading your ADR in the future is aware of what information isn't included as well as what information is confirmed or assumed.

As well as having to make assumptions about a historical decision you will also find that some information is completely missing. As mentioned above, you won't know all the options that were considered when an option was chosen. You could try to make assumptions, but sometimes there is so little information that making an assumption would just be a stab in the dark (very likely inaccurate).

In this case, you must highlight missing information. Anyone reading your ADR in the future must be aware of what information isn't included as well as what information is confirmed or assumed. Stating that the recording of the decision is being done in hindsight is another good way to show the reader to be wary of the information contained within.

Takeaways

The more comprehensive your ADRs the more you will see the benefits.

Even if you don't know all the facts, having some record of past decisions made is more useful than not. Even something that could seem obvious now may not be in 12 months.

• Any time your research turns up a past architecture decision make an ADR to record your findings.
• If nothing else create an ADR with the decision made and a note to say you don't have any more information. You at least then have something to refer to and iterate over.
• Get input from others to add information to your historical ADR.
• Use existing documentation and artefacts to find missing information for your historical ADR (version control messages can also be useful).
• Highlight assumptions and missing information for future readers.
• It can be a good idea to record decisions that have now been superseded and link to them from the ADR that supersedes them. You then have your history and reasoning preserved for future reference in case that decision is revisited again (even reversed!).

When you are recording a historical decision:

• use the same template that you use for new ADRs (if you need one I have a free template on the Communication Patterns website)
• set the status as decided or superseded, which you may want to qualify or add a note to indicate it was decided before being recorded (e.g. decided - historically)
• add the date the decision was made, which can be an estimated date if needed (e.g. estimated: Q2 2020)
• when recording the implications of the decision made you can add any implications that you now know about in hindsight (but label it as such)

Make life easier for future-you and your colleagues by filling in gaps in your historical documentation. The more comprehensive your ADRs the more you will see the benefits.

---

For more on ADRs check out Chapter 12 from the book Communication Patterns.

For everyone ready to learn more about software architecture or engage our architecture consulting services please get in touch.

©️ Read the Architecture Ltd.

---

1. This is not a decision-facilitating ADR (the decision is already made), so the options aren't for comparing potential choices but for understanding the trade-offs that were made. Sometimes an option is chosen due to flaws in an alternative, rather than a feature in the option itself. ↩

2. Identifying options that didn't exist or were cutting-edge at the time of the historical decision can be very useful in deciding if that decision needs to be reviewed with the new information and options available today. ↩