« Back to Blog

The Value of Documentation - A Caffeinated Example

By Ryan Veazey
Mar 5, 2018

Morning Rituals

For as many people in an office who drink coffee, there will probably be almost as many who don’t know how to make it. Despite being a relatively simple process, there can often be only one or two people who “know how to make the coffee.” When these people are late, sick or quit, things can turn ugly quickly. This is often called the “bus factor” - how much disruption if a person “got hit by a bus.”

A (Partially) Hypothetical Example

The office had a common automatic drip coffee maker. There was only one person in the office who made the coffee. They’d get into the office early, make a pot large enough for everyone, and then go about their day. No one thought about the process - as long as the coffee was flowing, there was’t an issue.

Then they were moved to a later shift, and there would be several hours without coffee unless something could be done. So a new person stepped in to create the coffee. It tasted different, worse. People started leaving the office to buy better coffee; over half a pot was thrown out almost ever day. One person suggested buying a pod system, but a quick calculation proved it to be far more expensive than even wasting half a pot a day.

Research was done, searches executed, experts consulted, and a wiki page was created and emailed to the office. Anyone who wanted to make coffee could consult the wiki! But they didn’t. Everyone knew there was a page somewhere but the email got lost and the search on the wiki was really never very good.

The instructions were distilled into a simple list - grind so many grams, dump into the filter, fill the reservoir with water, etc. The list was printed out and taped to the wall behind the coffee equipment. A scale and a better grinder were bought to ensure accuracy.

Things improved. More people started to make coffee - good coffee. Questions would arise and the documentation would be updated - a ratio of coffee to water so any amount could be brewed, grind sizes were specified, a note about requesting new beans and filters was added. A simple piece of paper made it so that even new employees or visitors could make consistently good coffee.

Good Documentation

Just like with coffee, dev teams can make the same mistakes with “the person who knows how to get the build to work,” or “the wiki page that’s somewhere that’s out of date.” Sometimes you have to invest in tools or processes that facilitate consistency in a process. Better processes can lead to faster results, higher quality, and happier teams. Here are some things to keep in mind.

Update Frequently

Documentation is something we all know we should do, but it’s often overlooked or put off for so long that it becomes very difficult to do accurately. Making small adjustment to the docs as needed generally leads to more useful docs.

Consider the Purpose

Drive Code Quality

Consider making documentation part of the definition of done for a new project. For some tasks, such as designing a new API, you may wish to start with documentation, which can help raise important questions early on. Knowing that you’ll have to document just the things that aren’t self-evident may encourage you to write clearer code. Be sure to explain things like why or when you would choose between similar classes or methods.

Get Feedback

Have a process for dealing with deficiencies in documentation. This can be something as simple as a pull request from a dev or an email from customers to report issues. Document your process for documentation.

It’s Never Done

Don’t be discouraged by how much there is left to document. Focus on making regular small improvements and you’ll be surprised how much progress you can make.