The state of documentation and why it’s failing IT and users

The state of project documentation is in disarray, and the impact that has on users, admins and developers grows every day. Jack Wallen has suggestions to avoid documentation deterioration.

Because of what I do, official documentation is something I have to depend on daily. Given the bulk of my writing is of a tutorial nature, I look to that documentation as a standard by which I am guided. Without that documentation, I would be left to my own devices to figure everything out. In some cases, that’s not so bad. But in some instances, official documentation is an absolute necessity so I can transform a rather challenging task into something just about anyone can handle.

SEE: Hiring kit: Python developer (TechRepublic Premium)

Thing is, not all documentation is created equal. And if I’ve learned anything over the past five or so years, it’s that depending on official documentation is like depending on a shoe to make you breakfast.

Simply put, the shoe can’t cook, and the documentation will fail you.

That’s a hard knock against a lot of projects (of all sizes). But anyone who’s had to use official documentation understands that the struggle is very much real. That official documentation is either out of date, broken or missing. To make matters worse, in many cases it’s up to you to figure this out.

Why does documentation fail?

Although this might not be your first question (when you run into poor documentation), it’s a necessary one to ask. I’ve found there are a few reasons why documentation fails a community. With certain software (such as Kubernetes), the projects are evolving so quickly that the organizers, employees and volunteers can’t keep up. When that happens, the first thing to go by the wayside is documentation. This is problematic, especially when a new release breaks features of previous iterations. I cannot tell you how many times I’ve had to resort to Kubernetes official documentation, only to find it doesn’t work. This has happened so frequently, that I don’t even bother with the official docs. Instead, I’ll either figure the problem out on my own, or I’ll locate a Mastodon or other service where users of the product hang out and may have solved the problem.

Another reason this happens is that a project simply doesn’t have the personnel to cover documentation. When that’s the case, the documentation starts out very sparse and gradually grows over time. But that doesn’t help early adopters or those who upgrade as soon as the new release is made available.

Yet another reason for this is that project maintainers create their tool for internal use only, don’t bother to write documentation, then eventually release the software to the public (forgetting they never wrote documentation at the start).

All three of these reasons point to what I call the deterioration of documentation. Unless documentation is regularly updated, it deteriorates and (eventually) becomes unusable. This is not a tenable situation.

Why good documentation is important

Simply put, when documentation deteriorates, users, admins and developers struggle to use a product. Or, worse, those same people have no other choice than to look elsewhere. In some cases, there is no elsewhere, so those users have no recourse but to do their best to figure out how to make things work.

SEE: Hiring kit: Back-end Developer (TechRepublic Premium)

That’s where I regularly find myself—struggling through the process of getting something to work. And it happens all the time. I just happen to have the luxury of over 20 years of doing this, so making poor documentation work is second nature to me. Unfortunately, that’s not so with everyone. And when a user, admin, or developer runs into yet another instance of documentation deterioration, the accompanying frustration can be daunting (especially when you have management breathing down your neck to get something up and running).

This is an especially important issue with open-source software, where users don’t have a company to reach out to for support. And because so many open-source projects can struggle to attract enough volunteers to keep documentation on pace with releases, it’s even more pronounced.

What can be done about deteriorating documentation?

First, larger projects need to place heightened importance on documentation. This should be an absolute no-brainer. And instead of relying on developers to write the documentation (because developers aren’t always the best at explaining something on an end-user or admin level), those projects should consider hiring a documentation team a must. Yes, it will have an associated cost, but the impact of having documentation that not only works but is easy to follow and will be measured in brand loyalty and continued growth.

For smaller projects (that can’t afford or attract a dedicated team for documentation), using volunteers is a must. But so many smaller projects have trouble with this. Not only have they not set up the process for creating effective documentation, but they also spend most of their recruitment time finding developers. Those smaller projects need to place a priority on assembling a team to ensure documentation is coherent, up-to-date and just plain works. Social media is a great way to find such people, but it takes time and effort. The reward for your effort will be the avoidance of documentation deterioration and happier users.

Until this happens, users, admins and developers will continue to struggle to integrate or use your project. When that occurs, those potential users will turn away and seek out another project. Can you afford that (and the reputation that might accompany such an event)?

It’s long past time that documentation became just as important an element to the project as the code. Until that happens, assume with every update you release something breaks in your how-tos, readmes and docs.

Let’s fix that problem now, rather than later.

Subscribe to TechRepublic’s How To Make Tech Work on YouTube for all the latest tech advice for business pros from Jack Wallen.