Document the Why, not just the How

Documentation is important. Everyone knows this, everyone agrees with this, it’s not really a topic of debate. It’s important to have your processes written down in some format to make ongoing work easier. If Person X wins the lottery and promptly quits, never to be seen again, can their duties be picked up by someone else relatively quickly? If you have good documentation, hopefully the answer is yes.

Unfortunately, documentation is too often confined to the how of the work, and leaves out the why.

Sure, you can lay out a step-by-step process of how to do a given task. That’s easy. I’ve written a great deal of process documentation in the last several years, with the intent of making life just that much easier for the next guy who fills that role.

What’s too often lacking is an explanation of why something is set up the way it is, or why a process has to be done a particular way. Maybe there’s a lot of tribal knowledge in your organization that covers these questions, but until someone documents that, it’s essentially useless.

If we don’t explain why a decision was made that led to the current state, it becomes much harder to work towards something better. Maybe there was a significant problem discovered along the way that required doing it a particular way. Maybe it was a budget constraint or lack of available resources. Maybe it’s just that no one thought of doing it any other way and that’s the way it’s always been done.

If no one documents the reasons, you’re condemning the next person to re-invent the wheel, to catch Sisyphus’s boulder and roll it back up the mountain themselves.

// 
// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 35
// 

“What is the best comment in source code you have ever encountered?” on stackoverflow, via the Internet Archive since the original thread was removed

I’ll be making an effort to include more of the why in my own documentation as part of my ongoing work, and for great justice the sake of your sanity and your successors, I’d encourage you to do the same.