Decision records

One of the things I’ve been terrible at is at keeping decisions records in projects. It happens often working on Tuist that I come across something that I need to know why it was done in a particular way and I can’t remember. It also happens that users ask about something and I have to repeat the same thing over an over. Because of that, I’m considering adding a decision record to the Tuist repository where we can keep track of these things, as well to the repos at Shopify that my team is responsible for maintaining.

As a developers we have to make many decisions along the day, and the result of those decisions is most of the times code. However, if the code doesn’t speak for itself, it’s extremely useful to add a companion narrative that adds the context necessary to understand the story of the code. It takes practice to build this habit, but I think it’s an important one to build as you become a more senior engineer. Piling up undocumented decisions in a project is the perfect recipe for misunderstandings and frustration.

I’m working on building that habit and making decision records a core piece of every repository that I’m responsible for maintaining.