Here is what the developer said to me: Why does the table have a column “uploaded by”? That wasn’t in our last meeting. Let me look at the design decision document I said to him.

Several minutes later, I told the developer that this column was added after our meeting (in which he also took part) since we thought it would be useful to the users. This is because people who work on the system will be able to track the tickets and ask the person who opened them questions if they need to. This will help them get the job done faster.

I have heard this type of question many times over the years from developers, product managers, project managers, and other designers from the design team about solutions the teams and I were working on.

The truth is, we can make any decision we want. It can be a good decision or a bad decision, but most times nobody remembers why. Including you. In this article, I will explain why it is crucial to document design decisions to be able to deal with these situations quickly.

What is a design decision document?

The design decision document is where all the decisions you and the team made about the design are recorded. For example, if you decide to divide a form into two parts instead of one, you can put it there. Another example could be when you decide to use a modal that asks the user to type the project name before deleting it. This documentation is referred to as a design decision document, and it contains all of the pertinent details about the design decision. I also pass it to the developers as part of the deliverables for the design to development handoff.

If people ask questions about the design, you will be able to clearly answer them

The design process involves showing the design to the team members, they ask questions, and we answer, but sometimes non-team members will ask about the design, it could be the customer success person, the quality assurance tester, or even the CEO. Whenever you write the decisions and the “why”, you are explaining them to yourself too, so when you have written it, you will be able to back it up and explain it to others.

What else needs to be in the decision document?

As part of the decisions, you must write why you and your team chose this decision over another. Most of the time no one in the team remembers the why, but the documentation will help. I also like to write the date when the decision was made and who was involved. Let me give you two examples:

• On 14.2.2022, the team decided to use a form with two steps. It is because we think it will make the task easier and allow the user to complete it in a more straightforward way.

• On 19.4.2022, the team agreed to split the implementation into two parts due to the complexity of the user story. This is due to the need to provide value to the user within the next week.

Communicate when you make changes to this document

Everyone needs to be on the same page when a decision is made. Send the information that you added to the document in a messaging app such as Teams or Slack right away to everyone who is involved. It looks like that.

“Hello team, after today’s meeting I updated the design decision document. Here is what I added: On 10.5.2022, we added a search component to the table because we think it will help users find what they are looking for.”

As you can see, it is a very simple communicative message that gets the team on the same page.

Keep it clean

It is important to keep this document clean. Delete any old information that is no longer relevant. If you don’t keep your documentation clean, you will find duplicate and conflicting information. In an agile world where decisions change fast, it is easy to get confused if the information is not organized.

Having clear design system documentation will save you time

Sometimes you have to make decisions that don’t depend on the use case, they come from best practices. For example, If you have three choices, use a radio button instead of a select component. When you have a good design system with clear documents, it can save you time to agree on small things that don’t need to be discussed. People who aren’t designers like inventing stuff about design, even though they aren’t experts. In these cases, having a clear design system will save you time talking to other stakeholders.

You can measure the impact of your decisions

Every design must be released to determine the level of acceptance. Let’s be honest, most of the time we don’t know how well the design will work. By writing your decisions and why you took them, you will be able to look at them and see where the assumptions worked and where they didn’t. If you connect the decisions with clear metrics, you will know how successful the design is.

For instance, you can write: We agreed to add a search field to the main page because we think that will help us to reduce the user’s search time by 30%.

Now that you can measure it, have you achieved your goal?

To conclude

A design document is an excellent means of communicating design decisions to the team. Writing it down helps you remember the decisions that were made about the design, and most importantly, it helps you remember why you made them. Keeping the documentation clean and transparent will let you back to it and answer questions about the decision and also let you measure the design by metrics.