Why insufficient documentation can create problems for developers

Why insufficient documentation can create problems for developers


Once again, Jack Wallen makes his case for documentation to keep up with the fast-as-light speed of developers.

developer working

Image: iStock/Deagreez

I want to preface this by asking you, dear reader, to not take this as seriously as it sounds. It was born of a place of frustration, while coming from a place of respect and a slight bit of tongue in cheek. That being said, recently I was working with an installation of Nextcloud when something strange happened. I wanted to install a supported app to the deployment and went about the usual business of doing so–installing from the Apps section of my admin account. I found the app I wanted to install, clicked Download And Enable, and Nextcloud went about the business of making it happen.

Must-read developer content

Only things didn’t go as planned. Just as the app installation completed, Nextcloud returned with an error page. No matter what I did, I couldn’t get back to the GUI to fix the problem. Since this wasn’t a virtual machine, I couldn’t roll back a snapshot.

What was I to do? I took a shot in the dark and managed to get the problem resolved (more on that solution in a bit). 

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

This issue does bring up a couple of problems with Nextcloud and a lot of other software out there. First is when an extension is listed as supported, the simple act of installing that add-on shouldn’t mess up the entire system. It’s an extension–not a kernel or the foundation of the whole. The second issue is much more important, and like the first, is not isolated to Nextcloud. That issue is documentation.

Let’s be honest here, poor or insufficient documentation is a widespread problem. When the software in question is open source, you might not have a company to turn to for help. When this happens, users and administrators often wind up in the dark, attempting to solve problems on their own. Because of this, those responsible for the applications must place a priority on proper, clear, and updated documentation. 

Of course this point is somewhat moot when you have a user or administrator capable of diving down rabbit hole after rabbit hole to resolve a situation that should either not have happened, or should be easier to figure out, thanks to proper documentation.

I’ve had this come up with so very many projects I’ve used or tried to use–from the small to the large. I cannot tell you how many times I’ve jumped into the Kubernetes water, only to find their documentation was out of date enough that what I was trying to do failed. That’s official documentation for a project that is recognized as the best container orchestrator on the market. I’ve found similar issues with Google’s documentation. Quite honestly, it’s been some time since I’ve actually come across documentation that was not only up to date, but concise, clear, and well written.

This issue is so bad, I’ve often thought about hiring myself out to companies for that purpose only. Then I remember how many businesses care so little about documentation, they’d rather leave users and admins to their own devices rather than actually spend the money and effort to keep their documentation on par with their product.

It’s a sad state of affairs. How bad is it? It’s so bad that I was trying to figure out that problem with Nextcloud and became frustrated enough with it to write this piece instead–that’s how rampant poor documentation is.

What was the problem?

Simply put, I was attempting to connect an instance of Nextcloud to an external storage provider. I logged on to my Nextcloud instance, and everything went down as I described earlier.

It was a mess.

In the end, the solution was really quite simple. I logged in to the server via SSH, and deleted the offending app folder from /var/www/html/nextcloud/apps. The following command did the trick:

sudo rm -rf /var/www/html/nextcloud/apps/files_external_dropbox

I was fortunate for a few things:

  1. I remembered which app caused the problem.
  2. I had the skills to troubleshoot the issue on my own.
  3. This wasn’t a production server for a client.

In other words, this situation could have been far worse. Of course, if this were a production server, I would have had the means to use a snapshot or a backup.

It shouldn’t have come to this, but it does–quite often. Admins and users everywhere run into similar situations, where documentation does them no good and they wind up having to either lean on company support (which is often a frustration in and of itself), or figure things out on their own.

This is especially true, given the nature of modern cloud-native software that is constantly updating with CI/CD and DevOps, where no one has time to document anything to match the scale, scope, and speed at which software evolves. 

It’s a problem with no clear solution.

Which, of course, is better than a solution with no clear problem–often the case in today’s agile world of buzzwords and technology for technology’s sake. 

Every so often, I just want to scream into the ether, “Either slow down app development or speed up documentation!” Either way, these two tasks need to reach some semblance of sync, before users wind up fed up and searching out other solutions, cloud-native or not.

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

Also see



Source link

Leave a Reply

Your email address will not be published. Required fields are marked *