Good Documentation is Caring

Commenting your code is like cleaning your bathroom—you never want to do it, but it really does create a more pleasant experience for you and your guests.1Ryan Campbell, “Successful Strategies for Commenting Code,” Particletree, August 1, 2005, http://particletree.com/features/successful-strategies-for-commenting-code/.

—Ryan Campbell

A significant amount of my work time time is spent reading help documentation. When I troubleshoot a problem or come up with a new solution, people ask me, “How did you know that?“

The truth is, I probably didn’t know until five minutes ago. I just looked it up.

The longer I’ve read documentation and forums, the more my mental palette has become attuned to what great documentation feels like, what terrible documentation feels like and worst of all, what it feels like when the documentation is nonexistent.

So why is documentation important? Here are my top three reasons.

  1. Thorough documentation shows that there are people who actually believe in the product.
  2. Documentation is an extension of the product itself.
  3. Good documentation shows care, respect, and anticipation of the users needs.

Without good documentation, and users are at the mercy of their own abilities to troubleshoot their problems. But when great docs exist, users are able to solve their problems and use the tools more effectively. When I find good documentation, it helps me trust the product and the people behind it.

The Challenge of Building Great Documentation

Writing great documentation is challenging. Technical writing is not glamourous. It will not get you featured in the Best American Essays series or earn a Pulitzer Prize. I don’t work on a dev team, but there are plenty of things that I can and should and will (someday soon) document for my current role—things like processes and workflow—but writing those things often gets deferred because there’s “actual work” to do right now. The truth is that documentation is just as much a part of the “actual work” as building new features or fixing bugs.

As I see it, the some of the main challenges for writing good documentation include:

  • determining what documentation needs to be written
  • actually writing the docs
  • maintaining the docs

Each of those tasks is a pretty sizable order on its own. And depending on the complexity of a product, those tasks could equal full time employment for an entire department. Given the weight of these tasks, I 100% sympathize with the solo maintainer of an open source tool who’s spending so much time building and maintaining the project that they don’t really have time to write docs. I’m just thankful that you put that thing you made on the internet.

I am far less sympathetic to companies with paid products and sizable customer bases and yet don’t have good documentation. Take some of your marketing dollars and reallocate them to documentation. Please write docs that actually show how to do things step-by-step process. Please make those docs searchable. Please invest in your information architecture. And don’t rely on your user forum to answer your user’s questions.

At the end of the day, any documentation is better than no documentation. It’s far better to find an austere README file that gives the lay of the land than to come across help docs that look like ¯\_(ツ)_/¯.

Scroll to Top