Document your product and software architecture decisions.

Hint: If you document your decisions, your future self will thank you!

For the past two years, I have been working on an interesting application modernization project. It involves moving a line of business from a decades-old monolith into a more modern SaaS application. As part of this journey, we had to make a lot of decisions! Do we need this particular feature? Solving this feature could be done in multiple ways, so which way is the right way? I knew that somewhere along the line, there would be questions about why we made this choice.

Why should we even attempt to document decisions?

Whether building new services or changing existing ones, we are constantly making choices in software development. Often, our choices are guided by what we know about the business, such as its complexity or our understanding of it when making the decision.

George Box said, "All models are wrong, but some are useful." Our models and designs become incorrect when we have a new understanding of the problem or uncover a different facet of the problem. Fast-forward six months or a few years. No one knows why the software behaves a certain way or why someone made this particular choice.

Are you having a moment of Deja Vu? When working on a project, look at a design or code and think, "Why did they do this? Why did they not consider option X?" I have been there. Decision Records shine here not just as a documentation tool but also to preserve the context of our design choices and why they were made.

It's not the destination; it's all about the journey. Decision Records are all about documenting the journey rather than just the decision. What question was trying to be answered? What choices were considered? Were there any known constraints to the chosen approach? Documenting these facets gives much more insight into the decision-making process. When a vital complexity is uncovered later, we can revisit our choice and see if the decision needs to be altered, given the new data.

I wanted to be kind to my future self, so I started tracking the decisions in my project. 

How I started

My design friends at the Times had an awesome one-pager template for pitching an idea or a potential project. Olivia Cheng introduced this to me. This one-pager frames the problem and the initial discussions that have turned ideas into potential projects. The goal is to orient the team, leadership, and stakeholders. The elements of this one-pager are:

• What is the Problem? Here, you describe the problem you are trying to solve and the critical implications.

• What is the Opportunity? What does solving this problem unlock for the business?

• List of your goals

• Success Metrics. How do you measure this?

• What are the Challenges? A brief description of each challenge.

• Team and Stakeholders impacted.

I knew the real intent of this template was for when you pitch an idea, but it has many of the correct elements of what I was looking for.

My first iteration of documenting decisions

Patterns and Pattern Language have taught me that a solution for any problem always has a context. So, I modified this template to contain the following elements. This was a free flowing document with Headings for each of these elements.

Context: I started with the context in a paragraph. The context describes the specific area applicable to the problem or dilemma we must solve.

Problem: What are we trying to solve specifically? I try to be as specific as possible here. Since people have read the context, they can now understand the questions much better.

Opportunity: Here, I describe why solving this problem is essential and how it improves things for the business or the user.  

Success Metrics: How do we measure this? What are some of the things we can measure?

Impacted Teams: Who are the folks going to be affected by this decision?

Known Challenges and Constraints: Do we know of any specific issues or things we will have to live with by making this decision? I document any important callouts here.

Open Questions: Initially, when attempting to solve the problem and looking at solutions, there could be many open questions that arise that we need to find answers to. I documented them in this section.

Recommended Decision: After deliberating and reviewing the findings, I use this section to document the agreed-upon decision.

Appendix: If I had several options that got evaluated as a result of answering this question, I documented each option as an Appendix along with its pros and cons.  

Toooooo Long!

I created a lot of my initial decision records in this fashion. It was highly informative. I have some of these documents from more than a year ago, and my present self is so thankful to my past self for doing this. But as I started to create more decision records using this template, I ran into these issues:

Too verbose: It had a lot of information. I didn't need to document things to the extent I was attempting to.

What’s the Status!?: Seeing the current standing on this decision by opening the document and scrolling to the end is too much time and effort. It's a decision document; we need to be able to see this quickly!

Adoption: I was the only one using and creating this. My colleague, Alex Silverman, who is a product manager gave me feedback that it needed to be easier to read and less verbose.

Although it was a fantastic start, after trying this approach for several months, I knew I had to evolve it. After all, if no one else is adopting this, then it's a big fail.

Iterating on the approach

Documenting Decisions is not new; it's a solved problem. I wanted to see how others in my space are doing this. I researched and read several takes on decision records. The one I found particularly interesting was Andrew Harmel-Law's: "Scaling the Practice of Architecture, Conversationally." In this article, among other important things, he talks about Decision Records as a thinking and recording tool. I was glad to find a lot of commonality in what I was doing and what he was describing. I loved the idea of the "Status". This would most definitely solve one of my problems I encountered.

I also remembered my Design Team's Research Plan document. The information was presented in a visually pleasing way, grouping the right information in a table and it was so easy to read and get to the right information points immediately! And this solved my other problem. Also, it wasn’t just a boring table, it was a visually pleasing table.

Once I made the changes, I immediately chatted with Alex, who had given me the initial feedback. He loved it. He and I reviewed and tweaked the document to group the related information. Spoiler Alert: The iteration described below is heavily used in my project. We have a template for it. And most importantly, I am not the only one creating these decision records.

Elements of my Decision Record

Status

When looking at the decision record, you must be able to immediately tell the decision's status. I took Andrew's suggested status but kept it to four values: Draft / Proposed / Adopted / Retired.

You can start the decision record when you only know the problem you are trying to solve. The status in this case is Draft. As you begin exploring the issue, you can start to document the other parts of the decision record, such as the Options Considered. When you're ready to recommend a choice, you can change the status to "Proposed ." and fill in the "Recommended Decision" section. You then circulate the decision record with the stakeholders/decision makers and have a meeting if that's how things are decided in your organization. Once you get their sign-off, you can change the status to "Accepted." When you have to revisit any accepted decision in light of new information, you can start a new ADR and mark this one as "Retired."

Action Items

Sometimes, you need to chat with other people. So, I added a list of checkboxes as a list of to-dos. This checkbox list reminds you of what you must do to move this decision forward.  

Question to decide on and Context

Question to decide on: Describe in a sentence what question you are trying to answer.

Context: Describe the context in which this question or problem applies. Anyone new to this problem or a new team member should be able to read the context and understand the question that is trying to be answered.

Recommended Decision, Supporting Arguments, and Consequences / Constraints

Recommended Decision: When starting with the decision record in the "Draft" status and you haven't explored all the choices, it is okay to leave this section blank. However, once you have considered all the options and your decision record is in the "Proposed" state, you can write down the decision you recommend.

Supporting Arguments: You note down why this option was favored amongst the other options.

Consequences / Constraints:  If there are any potential ramifications to this decision, whether positive or negative, document them here.  

Other Options Considered, Impacted Stakeholders, and References

Other Options Considered: When your decision record is in the "Draft" status, this is where you will be working most. As you explore each option, give it a name and start documenting the pros and cons.

Impacted Stakeholders: You can list the impacted stakeholders even when your decision record is in "Draft" mode. When you eventually propose the recommended option, i.e., and it is accepted, you can make a note of the specific people who have signed off on this decision.

Related References: Include any relevant artifacts in this section, such as meeting notes, documents, miro boards / figjam boards, and Slack threads, that are relevant to this decision-making.

What do you do with this decision record?  

You can create a markdown version or an Asciidoc template and check it in your source code repo. Alternatively, store the decision record as a Google doc in a folder designated for your team's relevant project.

Neurodivergent Friendly!

When I look back at the original iteration I had, my brain was struggling to quickly grasp all of the important points. When Alex, who also happens to be neurodivergent was feeling the same way, I knew I had to make changes. Not just to the parts of what goes into the decision record, but also how it is being presented. On a side note, when you accommodate the needs of neurodivergent folks, you end up making the whole thing better for everyone! The presentation and how the information is laid out makes a huge difference. Perhaps this is the reason for its successful adoption.

Additional References

• Andrew Harmel-Law’s, “Scaling the practice of Architecture, Conversationally”

• adr.github.io - There’s a wealth of information documented here including Michael Nygard’s gold standard of what should a light weight ADR contain.

• AWS Prescriptive Guidance - Using Architectural Decision Records to streamline technical decision-making for a software development project

Start documenting your decisions today!

Here's a link to the Google document that I now use as a template if you want to use this as well:

Product / Architecture Decision Record

Trust me, your future self will thank your past self! Do this now!