Making Documentation Useful

by erik johannessen

In my professional career, I've written my share of documentation. Some of it has turned out to be very useful, while other documents have ended up being a waste of my time. When I consider what the most useful docs had in common, I find that they generally fall into one of three categories:

  • Docs where I need to outline a policy/procedure/interface to someone where I’m not always able to do so in person (for people in other time zones, or other organizations)
  • Docs where I’m tired of getting asked the same question or having to convey the same information over and over again, and I just want to reply with a previously-given verbatim answer
  • Docs covering situations where I tend to forget how to do something infrequent and non-trivial, and want to write it down so I don’t have to remember

The attribute all three categories have in common is that, for various reasons, the document itself is referenced often, or at least often enough.

Documentation is only useful if it reflects reality, and we've all experienced the utter uselessness of reading legacy documentation that has fallen hopelessly out-of-date. Oh, the doc was initially good, but when something changed, no one cared to or remembered to update the documentation (if they even knew it existed at all!). The updater knew the system well enough to not need to ever reference the documentation, and so they never looked at it, and when they changed something, they simply informed everyone they thought needed to know about it directly. Maybe they sent an email explaining the update in detail. So helpful!

Whenever we encounter documentation that is not correct, presuming we have permission and ability to update it, there's a update diff threshold, an amount of effort we're willing to put in, above and beyond the effort needed to accomplish our primary task, towards updating the documentation associated with that task. Below this threshold, the effort seems low enough that we'll update the doc so that it's once again correct, but above it, we're bound to give up the document as hopeless and either a) start a new document (if doing so is easy enough to get below the threshold), or b) not bother at all. Sadly, for many of us, the update diff threshold is pretty close to zero, but a healthy organization should contain at least a decent subset of folks with a significantly higher update diff threshold.

If you want to encourage better documentation:

  • Your docs should be low-friction to update. Every bit of extra work it takes to update a document counts against the update diff threshold.
  • Start some basic documentation yourself. Even if it's incomplete, the effort to update existing documentation is (usually) far lower than the effort required to start a new document.
  • Your docs should be easily shareable. Docs that are not shareable and/or discoverable will be read by fewer people, and so will be referenced less often. Additionally, shareability decreases the likelihood that someone making a change will be unaware of the accompanying documentation that should be updated to reflect that change.
  • Relatedly, your documentation should live as close as possible to any systems and/or tools used as part of the thing being documented. Call this "organic discoverability." Tooltips, help buttons, notes taped to an appliance indicating where the manual can be found -- getting the existence of a document in the face of the user is critical.

Finally, I'll note that the best documentation is not necessarily written by the person with the most expertise in what is being documented. Rather, docs are often best written by those unfamiliar with a system, soon after their first successful effort doing the thing they're documenting, in consultation with an expert to make sure they get it right. Such newbies are often ideal, provided they can write in a language that is both clear and precise, as they will be the best judge of what information is obvious and what needs to be written down for the next newbie to come along.

In conclusion, not everything is worth documenting, but if it is, make sure it's discoverable, shareable, and easily updateable.