Why insufficient documentation can create problems for developers


Once again, Jack Wallen argues for documentation to keep up with the super-fast speed of developers.

Image: iStock / Deagreez

I want to preface this by asking you, dear reader, not to take this as seriously as it seems. It was born from a place of frustration, while coming from a place of respect and a slight irony. That being said, recently I was working with an installation of Nextcloud when something strange happened. I wanted to install a supported application for deployment and took care of the usual activity of doing so – installing from the Applications section of my administrator account. I found the app I wanted to install, clicked download and activate, and Nextcloud did it.

Must-read developer content

Only things did not go as planned. By the time the application installation was complete, Nextcloud came back with an error page. No matter what I did, I was unable to return to the GUI to resolve the issue. Since it was not a virtual machine, I was unable to undo a snapshot.

What should I do? I took a photo in the dark and managed to resolve the issue (more on this solution in a moment).

SEE: Top 5 Programming Languages ​​For System Administrators To Learn (Free PDF) (TechRepublic)

This issue raises some issues with Nextcloud and many other software. First of all, when an extension is listed as supported, just installing that add-on shouldn’t mess up the whole system. It is an extension – not a core or the foundation of the whole. The second problem is much more important, and like the first, is not isolated to Nextcloud. This problem is the documentation.

Let’s be honest here, poor or insufficient documentation is a common problem. When the software in question is open source, you may not have a company to turn to for help. When this happens, users and administrators often find themselves in the dark, trying to fix issues on their own. As a result, those responsible for the applications must prioritize appropriate, clear and up-to-date documentation.

Of course, this point is somewhat moot when you have a user or administrator who is able to dive into a rabbit hole after a rabbit hole to resolve a situation that shouldn’t have happened, or that should be easier to handle. understand, through appropriate documentation.

I have had so many projects that I have used or tried to use, from the smallest to the largest. I can’t tell you how many times I jumped into Kubernetes’ water, only to find that their documentation was outdated enough that what I was trying to do failed. It is official documentation for a project recognized as the best container orchestrator on the market. I found similar issues with the Google documentation. Quite honestly, it has been a while since I found documentation that was not only up to date, but concise, clear, and well written.

This problem is so serious that I have often thought of engaging in companies just for this purpose. Then I remember how many companies care so little about documentation that they’d rather leave users and administrators to their own devices than spend the money and effort to keep their documentation on par with their product. .

It is a sad situation. Is that bad ? This is so bad that I was trying to figure out this problem with Nextcloud and became frustrated enough to write this article instead – that’s how poor the documentation is.

What was the problem?

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

It was a mess.

In the end, the solution was really quite simple. I connected to the server via SSH and deleted the offending application 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 lucky for several things:

  1. I remembered which app caused the problem.
  2. I had the skills to solve the problem on my own.
  3. It was not a production server for a client.

In other words, this situation could have been much worse. Of course, if it was 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. Administrators and users everywhere find themselves in similar situations, where documentation is of no use to them and they end up having to either rely on corporate support (which is often a frustration in itself) or solve the problems on their own.

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

It is a problem with no clear solution.

Which, of course, is better than a clear problem-free solution – this is often the case in today’s agile world where buzzwords and tech for tech’s sake are all the rage. fashion.

Every once in a while, I just feel like screaming into the ether, “Slow down app development or speed up documentation!” Either way, these two tasks need to achieve some semblance of synchronization, before users are fed up and looking for other solutions, cloud native or not.

Subscribe to TechRepublic How to Make Technology Work on YouTube for all the latest technical advice for professionals at Jack Wallen’s business.

Also look


Sam D. Gomez