Documentation: Writing it is the Worst, Having it is the Best

Somewhere in the back of our minds, everyone working on a software project is aware that documentation is a very good thing to have. Despite this awareness, documentation is often prioritized lower than it should be.

Many understandable motivations contribute to documentation’s low prioritization. To prioritize documentation properly, we need to examine the Documentation-Discouragers© that an organization faces.

Documentation-Discourager 1: Nobody Is Going To Read It Anyway

A certain percentage of documentation may never get read, but documentation’s benefits outweigh the drawbacks of an occasional unread page. That said, documentation is not useful unless teams get in the habit of using it.

Any time you are asked a question, it is an opportunity to encourage the documentation-reading habit. If at all possible, don’t respond with an answer. Instead, kindly respond with a link to the documentation. If no documentation exists and it is a question likely to be asked again by others, create documentation first and respond with the link. In addition to saving future keystrokes, this creates a centralized information source. It eliminates the risk of getting outdated information if something changes, and getting this information is no longer dependent on someone answering an email.

Documentation-Discourager 2: Is What I’m Writing Actually Useful?

One of the biggest benefits of documentation is preventing problems from happening in the first place. Experiencing a problem is far more salient than one not happening, so it’s easy to forget how useful documentation can be.

Any time someone in an organization attributes a problem to communication issues, they are indirectly saying “this is something that could have been prevented with good documentation/willingness to read documentation”. With documentation, information is consistent, available at any time and can be updated immediately when a change occurs.

Some situations where I have found documentation most useful:

• Cross training/onboarding is easier: Recently, our team was temporarily without a QA tester. Instead of burdening an already busy QA department, I was able to use documentation to teach myself how to use our QA tools. New staff also benefits from this kind of documentation, filling in the blanks that inevitably occur in face-to-face training. They’re also not forced to rely on just memory to retain the substantial information presented in an onboarding process.
• Changes are less disruptive: In an organization, things constantly change, but it would be counterproductive to announce every change to everyone, and it’s not always clear who needs to know things such as new IPs, login URLs, and changed passwords. Documentation can prevent the panic that often occurs when something behaves differently than expected.
• Fewer meetings: On more than one occasion, I have been invited to a meeting to discuss a topic that I have already thoroughly documented. I decline the meeting, respond with a link to the documentation, and offer to reschedule if the documentation does not provide the necessary information. So far, this has eliminated the need for the meeting every time.
• Changes and improvements are much easier: Often, documentation about a system is most important when we are in the process of getting rid of it. If we are replacing a tool such as group chat or CRM, it is very important to know what kind of dependencies and uses this tool has before replacing it. Determining these dependencies just prior to migration is time consuming and includes a high risk of overlooking something critical.
• “I don’t know who to ask” isn’t a problem: Finding information on a wiki spares us from the awkwardness of trying to figure out who in the organization is able to answer the question.

Documentation-Discourager 3: Benefits Aren’t Easily Quantified

As shown above, documentation offers many benefits. They are difficult to measure because these benefits are often preventative, as opposed to value that is added. Some quantification can be done by reviewing past problems that could have been prevented with documentation, but such a measurement is dependent on problems occurring. It may be more useful to view documentation as the nutrition that fuels the measurable accomplishments that follow.

All of the benefits in the above “Is it actually useful” section are ones that ultimately save time and money. Among other things, documentation results in faster/more thorough employee onboarding, less time spent answering questions and searching for answers, and less redundant work hours spent collecting the same information. A well informed staff will yield greater returns.

Documentation-Discourager 4: My Manager Gets More Excited About New Features

New features are way more exciting than documentation. If software development was a meal, documentation would be the vegetables (without dip). Managers need to look inward and remember how valuable this documentation will be in a few months. Realizing the future problems that documentation prevents should be enough to fuel some morale-boosting enthusiasm.

Documentation-Discourager 5: I Can’t Find Time To Do It — Everyone Is Asking For Software, Not Documentation!

Documentation time needs to be scheduled like other tasks. It’s possible to include documentation time as part of a production schedule, but it is still quite easy to relegate it to the “will-get-around-to-it-later” pile.

My team has found success with writing documentation on our flex days. We are fortunate to have one day a week where we are not required to work on current projects. One of the most productive uses of this time has been *actually* working on the will-get-around-to-it-later pile that documentation typically languishes in.

Documentation-Discourager 6: Coding Is Significantly More Enjoyable Than Writing Documentation

Honestly, this one is true, can’t debunk it. Building something generates way more endorphins than writing about it.

The only thing I can say is that documentation will significantly reduce the number of future meetings and questions that need answering, which frees up time to do more coding.

In Conclusion

I think my stance on documentation is clear by now. Although it is not at all flashy, and not an ideal way to spend an afternoon, the benefits are enormous. At ITHAKA, our documentation is provided as a wiki using Atlassian’s Confluence.

ITHAKA is the first organization I’ve worked for with an internal wiki that covers anything beyond basic HR information. I still think of previous jobs, and how many issues could have been easily addressed had we been using an internal wiki. Additionally, being in a team and organization that values and makes time for tasks like documentation is refreshing. Getting an organization on the same page is significantly easier when you can refer them to a literal page.