The state of project documentation is messy and the impact on users, admins and developers increases every day. Jack Wallen has suggestions for avoiding document damage.
Because of what I do, official documentation is something I have to depend on on a daily basis. Since much of my writing is instructive, I consider that document the standard by which I am guided. Without that documentation, I would leave things to my own devices to figure things out. In some cases, that’s not too bad. But in some cases, official documentation is an absolute necessity for me to be able to transform a rather daunting task into something anyone can handle.
SEE: Recruitment Toolkit: Python Developer (TechRepublic Premium)
The thing is, not all documents are created equal. And if I’ve learned anything over the past 5+ years, depending on official documentation is like depending on a shoe to make you breakfast.
Simply put, the shoe cannot cook and the document will fail.
That’s a hard hit for a lot of projects (of any size). But anyone who has ever had to use official documentation understands that the struggle is very real. That official document is either outdated, corrupted or missing. To make matters worse, in many cases you have to figure this out.
Why does the document fail?
While this may not be your first question (when you encounter poor documentation), it is an essential question to ask. I realize there are a number of reasons why documentation fails in a community. With certain software (such as Kubernetes), projects are evolving so quickly that organizers, staff, and volunteers can’t keep up. When that happens, the first thing to do is documentation. This is problematic, especially when a new release breaks features of previous iterations. I can’t tell you how many times I’ve had to resort to the official Kubernetes documentation, only to find that it doesn’t work. This happened so often, that I didn’t even bother with the official docs. Instead, I’ll find the problem myself, or I’ll find Mastodon or another 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 provide documentation. At that time, the documentation began to be very sparse and gradually grew over time. But that doesn’t help early adopters or those upgrading soon after a new release is made available.
Yet another reason for this is that the project maintainers create their stuff just for internal use, don’t bother writing the documentation, then eventually release the software to the public. (forgot that they never wrote the documentation at the start).
All three of these reasons point to what I call damaged documentation. Unless the document is regularly updated, the document will deteriorate and (eventually) become unusable. This is not a rentable situation.
Why is good documentation important
Simply put, when documentation goes bad, users, administrators, and developers struggle to use a product. Or worse, those people themselves have no choice but to look elsewhere. In some cases, there’s nowhere else, so those users have no recourse other than to do their best to figure out how to make things work.
SEE: Recruitment Toolkit: Back-end Developer (TechRepublic Premium)
That’s where I often find myself — struggling to get things done. And it happens all the time. I just happen to have 20+ years in this job, so creating poor documentation is second nature to me. Unfortunately, that’s not the case for everyone. And when a user, admin, or developer encounters another instance of document corruption, the accompanying frustration can frustrate you (especially when management has to do their best. power to start the activity).
This is a particularly important issue for open source software that the user does not have a company to contact for support. And because so many open source projects can struggle to get enough volunteers to keep the document on track for release, that’s even more obvious.
What can be done when the quality of the document is degraded?
First, larger projects need to place a high emphasis on documentation. This is an absolute no-brainer. And instead of relying on developers for documentation (since developers aren’t always the best at explaining something at the end-user or admin level), those projects should Consider hiring a document team. Yes, it will have an associated cost, but the impact of having documentation is not only functional but easy to track and will be measured by brand loyalty and ongoing growth.
For smaller projects (which can’t afford or can’t attract a dedicated document team), the use of volunteers is a must. But a lot of smaller projects struggle with this. Not only do they not set up an efficient documentation generation process, but they also spend most of their recruiting time looking for developers. Those smaller projects should prioritize assembling a team to ensure the documents are coherent, up-to-date, and simple 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 document damage and happier users.
Until this happens, users, admins, and developers will continue to 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 might come with such an event)?
For a long time now, documentation became as important to a project as the code. Until that happens, let’s say with each update you release some bug in your tutorials, readings, and documentation.
Fix that problem now, instead of later.
Subscribe to TechRepublic’s How to make technology work on YouTube for all the latest tech advice for business professionals from Jack Wallen.
