The Importance of Documentation in the Workplace

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 occurs 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 adjustments as needed generally leads to more useful documents.

Consider the Purpose

  • High Level for Developers - For high-level docs, focus on the big-picture interface, build/setup steps, requirements, and purpose. A new developer should be able to get a dev environment set up with these docs with minimal effort. Don’t worry about overly-detailed explanations for patterns that are common to the language, such as how to use the package manager, but do make sure to mention which one you are using (I’m looking at you, JavaScript devs) and consider providing a link to the homepage or any additional documentation specific to that system. These should be stored with the code, such as in a README file at the top level of the repository in a format friendly for terminal and web, such as Markdown or ReStructuredText. Optionally, additional documentation can be included at the top level of a folder for a component that needs its own documentation.
  • Autogenerated - Virtually every language in current use has some (or multiple) ways of generating docs from the code. These systems may allow or even require information to be added in comments above methods or classes. Some standards are a lot more verbose than others, so you’ll want to consult the recommended style for the language and doc tool you’ve chosen. Looking at these may help you choose among competing tools. In general, be clear but concise; don’t feel the need to over-explain the obvious, such as the meaning of a parameter named user_id.
  • Comments - These should be rare. Use them to explain to people looking at your code (which may be yourself in the future) why you’ve done something unusual - things like “legacy hacks” or code that does something other than what it appears to be doing. Ideally, the code you write can avoid this with good naming conventions and proper abstractions. For example, using a method for its side effects (which may be a concern in itself) or for a purpose other than its primary one can be made more clear by renaming, aliasing or wrapping the method.
  • Customer/User Facing - If you have the luxury of having coworkers who interact with users regularly, you’ll want to involve them in these docs. Start off with the basics and grow these as needed. Make sure and update these when you change things they see.

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.

Protect Your Business Data

We are passionate about helping our customers protect their data. We want you to use Jungle Disk to protect yours. Click on Sign Up to get started. It takes less than 5 minutes!

Sign Up