Software makers have gotten worse at documentation and here's why that's a problem

Documentation is an aspect of development that is often overlooked. Find out why Jack Wallen believes this needs to change.

Software developer freelancer woman working at night

Image: iStockphoto/monstArrr_

As you might know, I write a lot of tutorials. On any given week, I might pen anywhere from seven to 10 such articles. I've also been an administrator for a number of clients which means I work with a lot of software, much of it open source. Because of that, I read quite a bit of documentation. This is a necessity, especially when you're working with a new piece of software, or something that's been around, but unfamiliar.

I've been doing this for over 20 years. 

One common thread I've found over time is that documentation has gotten progressively worse. This isn't just small open source projects, it's large projects that even enterprise-level companies depend on. In fact, in some instances, the documentation has become so bad that it's impossible to get software working without a struggle.

Admins don't have time for failed documentation, especially in a world that's not only in a constant state of evolution, but where the competition to remain relevant and ahead of the game has become maddening.

Yet, it's a crapshoot if any given piece of documentation will help you get the server or client software you desperately need up and running.

SEE: Top 5 programming languages for systems admins to learn (free PDF) (TechRepublic)

Why is this happening?

The landscape of software development is always changing and because business is evolving so fast, developers must keep up or be left behind. Because of this, the software changes exponentially faster than the documentation. 

When a business tells a developer, "We need your software to function this way," so long as that request makes sense (and, in the case of open source, can benefit others), said developer or developers, makes it happen. In many instances, the software engineer makes those changes as fast as possible. With such occurrences, that engineer may or may not remember to update the documentation. Or, they may find themselves in a situation where their development pipeline is so backed up, they simply don't have time to update those docs, READMEs, and main pages. 

Then, the documentation goes stagnant. Users and admins come along, attempt to employ the product, and only find they have to look elsewhere to get it up and running. 

I cannot tell you how many times I've wanted to get a piece of the Kubernetes puzzle up and running, only to find the official documentation doesn't work. There'll be a command to run, but said command doesn't work.

What gives?

To be fair, we all know Kubernetes is one of the hottest projects on the planet, so it's understandable that documentation might be the last thing on their mind.

Think about it: How many admins depend on that documentation? How many new Kubernetes users are there every single day? And how many times do those users head over to the official documentation, only to become immediately confused as to why they can't get something working. They followed the documentation to the letter. They know they did everything right. And yet, they find no success. After a bit of googling, they finally discover the solution, only to realize the official documentation is wrong.

What can be done about this?

Every project needs to remember that the public depends on their documentation. Without a public (which includes admins, users, and other developers) able to get their product to install or function properly, said public will turn to another solution. Even though documentation might be at the bottom of the to-do list, it needs your attention, or else you risk losing users/customers/businesses.

It only takes one developer to toss their arms up in the air to say, "I'm done with trying to make this project work," before a fork or similar project is created--one with up-to-date documentation that can actually help admins and devs get the software installed and working. 

If I sound a bit jaded, it's because this particular issue has burned me more times than I care to count. I've wasted hours on projects, simply because documentation was either out of date, poorly written, or simply wrong. That issue reflects directly back to the project at hand--to the developers, to the company. 

But what to do?

The ideal solution, which may or may not be possible for all projects, is to hire people with the sole task of keeping documentation up to date, well written, and correct. With open source projects this could be an easy win. Why? Because there are plenty of people out there who'd love to volunteer for a project, but aren't developers. That's an easy win. For proprietary projects, companies need to be open to hiring documentation specialists, either on a full-time or contractual basis, to not only write documentation but to keep it up to date as the software evolves (not after).

Yes, hiring for such a job might be a tough ask for big business, but if you want admins and users to have faith in your product, this should be considered a must. People are only willing to hand out so many passes before they turn to another project.

Don't be the project people leave. Be the project people turn to.

Also see