Link Search Menu Expand Document

Keep track of why decisions were made and features built

This will help you keep track of original reasoning when the feature was built and allow you to see if the circumstances have changed enough to further develop something.

Using a tool such as Trello to keep track of a backlog and work in progress is necessary. The changes should be documented in reasonable detail so as there is no miscommunication.

Besides the what we’ve found that including the why was also very useful. The why covers two things: why something is being built, and why it is being built this way.

Consistently keeping track of your reasoning means you’ll have a central repository to check when you need to find out why things were done the way they were. Knowing why things are a certain way makes it easier to decide if they can be changed.

Similarly, as the number of features increases, you’ll likely have to remove some. If you know why you built something, you can decide if you can remove it or if it’s still worth maintaining.

Initially, we started doing this when working on supplier commission structures. We documented our reasoning behind the figures we decided on. At the same time, I also implemented a per-supplier override. While we didn’t need or use it immediately, I explained that I thought we might need it soon.

The example here is technical, but it’s wise to do this for processes as well. Document the why of all the steps in a process and periodically check whether the reasoning still stands.

We used tickets, but over time it’ll probably become too troublesome. Instead, a Wiki or a user manual would eventually be better.

Tracking the “why” is also important but more difficult

Tools can often track the ‘what’ quite well and accurately. But you can only track the ‘why’ manually.

We did this by being as verbose as possible in our tickets. We explained the reasoning behind the feature and the goals it aims to achieve. I also explicitly mentioned and non-obvious technical decisions.

Our tickets ended up being part of the documentation. We could refer to them

Related Lessons


Suggest an improvement to this page (me@ognjen.io)