The state of documentation and why it fails IT and users

The state of project documentation is in disarray, and the impact this has on users, admins, and developers is growing every day. Jack Wallen has some suggestions for avoiding documentation deterioration.

Image: Adobe Stock/greenbutterfly

Because of what I do, official documentation is something I have to rely on on a daily basis. Since most of my writing is didactic in nature, I consider this documentation to be a standard by which I am guided. Without this documentation, I would be left on my own to figure it all out. In some cases, it’s not so bad. But in some cases, official documentation is an absolute necessity so that I can turn a rather difficult task into something anyone can handle.

TO SEE: Recruitment Kit: Python Developer (TechRepublic Premium)

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

Simply put, the shoe can’t cook and you’ll miss the documentation.

It’s a blow against many projects (of all sizes). But anyone who has had to use official documents understands that the struggle is very real. This official documentation is either outdated, broken or missing. To make matters worse, in many cases it’s up to you to find out.

Why does the documentation fail?

While this may not be your first question (when encountering poor documentation), it is necessary to ask. I discovered that there are several reasons why documentation fails in a community. With some software (like Kubernetes), projects move so fast that organizers, employees, and volunteers can’t keep up. When this happens, the first thing to overlook is documentation. This is problematic, especially when a new release breaks functionality from previous iterations. I can’t tell you how many times I had to resort to the official Kubernetes documentation, only to find that it didn’t work. It happened so many times that I don’t even care about official documents. Instead, I will either find the problem on my own, or 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 staff to cover the documentation. When this is the case, the documentation starts out very sparse and grows gradually over time. But that doesn’t help first-time users or those who upgrade as soon as the new version is released.

Another reason for this is that the people behind the project create their tool for internal use only, don’t bother to write documentation, and then eventually release the software to the public (forgetting that they never wrote any documentation at the beginning).

These three reasons point to what I call deterioration of documentation. If the documentation is not 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, administrators, and developers find it difficult to use a product. Or, worse, these same people have no choice but to look elsewhere. In some cases, there is no elsewhere, so these users have no recourse but to do their best to figure out how to make things work.

TO SEE: Recruitment Kit: Back-end Developer (TechRepublic Premium)

This is where I regularly find myself struggling in the process of making something work. And it happens all the time. I happen to have the luxury of doing this for over 20 years, so doing poor documentation work is second nature to me. Unfortunately, this is not the case for everyone. And when a user, admin, or developer runs into another case of documentation deterioration, the frustration that comes with it can be daunting (especially when you have management at their wits end to get something up and running) .

This is a particularly big problem with open source software, where users don’t have a company to contact for help. And because so many open source projects can struggle to attract enough volunteers to keep the documentation at the pace of releases, it’s even more pronounced.

What can be done against the deterioration of the documentation?

First, large projects should place increased emphasis on documentation. This should be an absolute no-brainer. And instead of relying on developers to write documentation (because developers aren’t always the best at explaining something at the end-user or admin level), these projects should consider hiring a team of documentation. 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 (which cannot afford or attract a dedicated documentation team), the use of volunteers is essential. But so many small projects have problems with this. Not only do they not have the process in place to create effective documentation, but they also spend most of their recruiting time finding developers. These smaller projects should prioritize building a team to make sure the documentation is consistent, up-to-date, and just works. Social media is a great way to find such people, but it takes time and effort. The reward for your efforts will be less documentation deterioration and happier users.

Until that happens, users, admins, and developers will continue to struggle to integrate or use your project. When this happens, these potential users turn away and look for another project. Can you afford that (and the reputation that might come with such an event)?

It is high time that documentation became as important a part of the project as the code. Until that happens, assume that with every update you release something that breaks in your how-to guides, readmes, and docs.

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

Subscribe to TechRepublic How to make technology work on YouTube for all the latest tech tips for professionals from Jack Wallen.

Sam D. Gomez