Thoughts on Decision Documents

​

When you start a new project or significant feature, it's likely that you've written a technical specification. Tech specs often lay out the overall design of a system or feature such that it can be implemented by following the spec. Tech specs answer the question, "how?" Knowing how to build something is useful, but there's an equally important question: “why?” That’s where decision documents come in.

A decision document outlines the thought process around a specific technical decision. Each document focuses on one high-level decision and breaks it down into several sections. While there is no one standard for design documents, here are some common sections you might find:

Background. Also sometimes called “context,” this describes any relevant information the reader might need to understand the environment in which the decision is made. This section includes historical information as well as introducing the various data or metrics involved in the decision making process.

Decision. The actual decision that was made. This is typically short, maybe one to three sentences, and describes the decision in plain, clear language.

Rationale. This is sometimes included in the decision section and sometimes separate, but in either case, walks through the reasoning behind the decision. Sometimes this section also includes alternative solutions that were explored and why they were not acceptable.

Consequences. What happens as a result of the decision that was made? How does this decision affect the software you’re working on? What does it preclude? What problems does this decision solve or avoid?

Decision documents are typically not very long, maybe a page or two, but represent a key moment in the software’s lifecycle. These decisions, sometimes small, sometimes large, provide important context that can easily be lost over time. Especially as team members cycle on and off a project, there is this institutional knowledge that can save people time and energy.

No one becomes a software engineer because they want to write documentation all day, but documenting things makes your life much easier. How many times have you been working on some code and wondered, “why are we doing things this way?” If you have an archive of decision documents to search, you can get that answer quickly. That’s why projects like Remix and Epic Web have started including decision documents in their repositories for everyone to see. (This is also something I’m looking at incorporating into my own projects, as well.)

So, the next time a major decision is made on the software you’re working on, take a moment to write down the decision in a document that you can refer to later. Your future self will thank you.

Key Takeaways

• Decision documents describe the “why?” of a technical decision.
• Decision documents need not be long to be effective.
• The knowledge represented in decision documents otherwise might only live in team members’ heads, and then be lost when they leave.

More about Decision Documents

📝 Documenting architecture decisions by Michael Nygard
Architectural Design Records (ADRs) are a type of decision document. Another resource on ADRs, this post describes why you'd want to use an ADR and the post itself is formatted as an ADR. Nygard is credited with coining the term "architectural decision record."

📝 ADR Process by Amazon Web Services
AWS' resources for working with ADRs. Includes best practices and a sample ADR.

📝 Documenting design decisions with RFCs and ADRs by Bruno Scheufler
An overview of how RFCs and ADRs can be used together to better document technical decisions made on any project.

📚 Managing Your Interrupt Rate as a Tech Lead. Are you a tech lead struggling with managing your time? Are there too many interruptions in your day, making it difficult to get your coding work done? If so, this FREE e-book is for you.

Stuff I've Enjoyed This Month

📚 Quit by Annie Duke
I picked up this book thinking it would be about quitting your job, but it's actually much more. The book is really a decision making guide to help you quit any decision effectively. It goes through the cognitive traps that keep us from stopping when all the red flags are there. Great read.

🎬 How to Write Better Test Names by Artem Zakharchenko
This short video explains how to write effective, concise test names in your JavaScript tests. I'm going through and updating my project tests to reflect some of the practices in this video.

📝 The origin private file system by Thomas Steiner
Up until two weeks ago, I had no idea that the origin private file system (OPFS) existed in browsers. This in-browser file system is a way for web applications to save files in the browser that are tied to the app's origin. This post gives an exhaustive overview of OPFS.

📚 Cured by Jeffrey Rediger, M.D.
If you've been following me for any amount of time, you'll know that I've had many health challenges over the past couple of decades. This book is inspirational, as it details cases of spontaneous remission from chronic and fatal diagnoses. If you or anyone you care about is struggling with their health, this book can inject some much-needed hope into the situation.

📝 12 Modern CSS One-Line Upgrades by Stephanie Eckles
CSS has changed a lot in the last couple years, so much so that tricky appearances and layouts have become surprisingly easy. This post is a nice catchup of the past couple years of CSS features that will allow you to replace a bunch of CSS and HTML with a single CSS property.

What I'm Working On

🏠 Real Estate: I've got one property that is currently costing me a lot of money in repairs. It appears that there was a rat infestation and those little guys caused all kinds of damage. I think we have it under control now, but fingers crossed. For another property, the property manager came into the office to find the keys on his desk and apparently the tenants just left without notice. Just another month in the life of a landlord. Follow my Instagram for real estate photos.

💻 humanfs: I released humanfs, my newest open source project. This project reimagines JavaScript file APIs to eliminate some of the major annoyances we've been dealing with for years. You can read the intro blog post for more.

💻 Open Source: I released Retry, a little utility that lets you seamlessly retry failed async function calls in JavaScript. I extracted this utility from humanfs as it seemed like a useful tool on its own.

💻 ESLint: ESLint v9.0.0-alpha.2 has been released! We are getting very close to beta with just a couple of items left. You can follow the progress on our project board.