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.

What are the reasons for documenting design decisions?

From my point of view, this document is important because:

You and the team will not remember the decision you made

When we design we are very focused on the task. However, 3 weeks later, when the task is handed over to the developers, we can’t remember every single detail. Therefore, if it is written down then we don’t have to remember it.

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.

It is a transparent source of truth people can look at

When someone asks you why, you can send him/her the documentation and say, “Look at this document, it is in there.”. It will save you slack messages and calls.

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.

Where should you write this document?

It is better to write it in a place everyone knows and has access to. I believe it should be written on a documentation tool like Confluence or a Notion page. Avoid using design tools like Figma, as this is not the right tool for this task.

When writing this documentation?

Whether it is a small decision or a big decision, it is better to update it as soon as the decision is made. If you don’t do it immediately after the decision has been made, you might forget important information or forget to add it at all.

Who should write this documentation?

According to my opinion, only one person should own it, and that is the product designer. The designer is the person who is responsible for the design, and he or she is the right person for this task.

Write it simply

Write each paragraph simply, avoiding too many words. Use simple words to explain the relevant decision information.

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.

Thank you for reading the article. I hope that the article helped you understand why it is important to document the design decisions and how it can help you in the design process.
Please feel free to share it with your friends or members of your team, and if you have any questions, please let me know.

If you enjoyed my article, I suggest you follow me and subscribe so you’ll receive an email whenever I post.

Want to get the most out of Medium? Click here to become a member. As a member, you’ll support me and lots of other writers.