Considering how smart developers are, the easiness with which they forget the history of their own projects can be mind boggling. How many times have you tracked a bug down until you’ve found the exact change that introduced it, yet the responsible developer couldn’t remember why that change was made?

Even more commonly, developers as a group forget things faster than a goldfish. The first time a developer enters a codebase new to her, she will definitely raise questions regarding design and implementation choices. If she’s lucky, half of her questions would have valid answers. More often, though, most questions would result in a shrug and “it seemed like the right way”, or the dreaded “that was done by X, he left two months ago.”

When your team inevitably decides to make changes to a system, how much time gets wasted trying to decipher whether a certain solution was picked because it was actually necessary, or because it looked cool?

While documentation might be frowned upon, even the most ad-hoc and straightforward solutions can be a huge help to a growing team. I like to instill in teams a simple journaling habit of keeping a Change-log-ish file for non trivial decisions, usually in the internal wiki.

Are you upgrading a dependency? Write down whether the upgrade was needed in order to use some new capability, solve a bug or just routine maintenance. If while working on a new feature the team decides to do that particular part in an approach that differs from the rest of the project, write down the reasoning behind it.

These 2-3 sentences are easy to write (think team Slack message that actually gets saved in a proper place) and priceless. 6 months from now, when shit hits the fan and someone’s staying up late to solve some scaling issues that are affecting your biggest client, you’ll thank past-you so much for making sure you will all remember why it was so important not to parallelize the serialization of those requests, update that library or change the query structure.