The state of the project documentation is in disarray and the impact it has on users, administrators and developers is growing every day. Jack Wallen has suggestions to prevent deterioration of the documentation.
Because of what I do, official documentation is something I depend on on a daily basis. Since most of my writing is tutorials, I look to that documentation as a standard that guides me. Without that documentation, I’d be left to figure everything out. In some cases, that’s not so bad. But in some cases, official documentation is an absolute necessity, so I can turn a rather challenging task into something almost anyone can handle.
SEE: Hiring Kit: Python Developer (Tech Republic Premium)
The point is that not all documentation is created equal. And if there’s one thing I’ve learned over the past five years or so, it’s that relying on official documentation is like relying on a shoe to make your breakfast.
Simply put, the shoe can’t boil and the documentation will let you down.
That’s a hard blow to many projects (of any size). But anyone who has had to use official documentation understands that the struggle is very real. That official documentation is outdated, broken or missing. To make matters worse, in many cases it’s up to you to figure this out.
Why does documentation fail?
While this may not be your first question (when you come across bad documentation), it’s a necessary one. I’ve found there are a few reasons why community documentation fails. With certain software (like Kubernetes), the projects evolve so quickly that the organizers, collaborators and volunteers can’t keep up. When that happens, the first thing you need to do is get the documentation. This is problematic, especially when a new release breaks features from previous iterations. I can’t tell you how many times I’ve had to resort to the official Kubernetes documentation, only to find it doesn’t work. This has happened so many times that I don’t even bother with the official documents. Instead, I sort out the problem myself, or find 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 documentation. If so, the documentation starts out very sparse and gradually grows over time. But that won’t help early adopters or those who upgrade once the new release is available.
Yet another reason for this is that project managers make their tool for internal use only, don’t bother writing documentation, and eventually release the software to the public (forget they never wrote documentation in the beginning).
All three of these reasons point to what I call the deterioration of the documentation. Unless the documentation is regularly updated, it deteriorates and becomes (eventually) unusable. This is not a sustainable situation.
Why good documentation is important
Simply put, when documentation deteriorates, users, administrators, and developers struggle to use a product. Or worse, those same people have no choice but to look elsewhere. In some cases, there is nowhere else, so those users have no recourse but to try their best to figure out how to make things work.
SEE: Hiring Kit: Back-end Developer (Tech Republic Premium)
That’s where I regularly find myself – struggling through the process of getting something to work. And it happens all the time. I happen to have the luxury of over 20 years of doing this, so making bad documentation is second nature to me. Unfortunately, that’s not the case with everyone. And when a user, administrator, or developer encounters yet another case of documentation degradation, the frustration that comes with it can be disheartening (especially if management is breathing down your neck to get something going).
This is a particularly important problem with: open source software, where users have no company to contact for support. And because so many open source projects can struggle to attract enough volunteers to keep documentation up to date with the releases, it’s even more obvious.
What can be done about deteriorating documentation?
First, larger projects should place more 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 at the end-user or admin level), those projects should consider hiring a documentation team as a must. Yes, there is a cost, but the impact of documentation that not only works, but is easy to follow and measured in brand loyalty and continued growth.
For smaller projects (which cannot afford or attract a dedicated documentation team), the use of volunteers is a must. But so many smaller projects struggle with this. Not only have they failed to set up the process for creating effective documentation, but they also spend most of their recruiting time finding developers. Those smaller projects should prioritize assembling a team to make sure the documentation is coherent, 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 effort is avoiding documentation degradation and happier users.
Until this happens, users, administrators, and developers will struggle to integrate or use your project. When that happens, those potential users will turn away and look for another project. Can you afford that (and the reputation that comes with such an event)?
It’s been a long time since documentation became as important a project element as code. Until that happens, assume that with every update you release something breaks in your how-to’s, readme’s and docs.
Let’s solve that problem now, not later.
Subscribe to TechRepublic’s How to make technology work on YouTube for all the latest technical advice for business professionals from Jack Wallen.
