Open Source

The big Linux Achilles: Documentation

Linux does have one glaring Achilles heel -- documentation. Jack Wallen has a proposed solution for this problem.

Over the last week I have read numerous articles bemoaning the sad state of Linux documentation, and I have to say - I am on board. Linux is an outstanding operating system. There is very little it can not do. The biggest problem (especially for the new user) is getting there.

Man pages are pretty much worthless for new users; the Linux Documentation Project is a failure (I just pulled up an article on "Automounting" dated 2002-12-27, and Google searches bring up mostly forum posts). This, of course, is not to say that developers of applications aren't doing their part. When an application has a help document included, they certainly can be helpful. For instance: the Claws Mail "Manual" entry in the Help menu takes you to the online Claws Mail User Manual - a very useful site.

The included OpenOffice manual is very helpful and massive.

But there are other applications that don't hold up so much. And some applications don't even install the documentation by default. GnuCash is one of them. If you want documentation, you have to install it separately. Sure that's a no-brainer for some of us, but for many, it just fails to compute. And that's where my problem begins.

Linux applications should install with documentation by default. No questions asked. There should not be a point in the installation (of the OS or the application) where it asks you if you want to install relevant documentation. It should just be there. And when a user installs an application with The Ubuntu Software Center (or Synaptic, or apt, or yum, or urpmi), that documentation should automatically be installed. This, of course, is trivial. The real problem is the documentation itself.

I will preface this next section with the statement that there are exceptions. The OpenOffice and GnuCash (when installed) documentation are quite good. However...

As a whole, Linux documentation is poor. The reasons for this are numerous. But I will focus on two of those reasons: Lack of developer support and laziness. Let's address the former.

On numerous occasions, I have offered my assistance to write documentation for a project. But even though this offer is met with open arms, it falls short because the developers become shortsghted with getting their project out into the public as soon as possible. They seem to forget there is not a business model that could crumble if their project is delayed. And releasing a project without documentation is only asking for failure. If a developer is not capable of writing documentation, it is their duty (as much as it is writing efficient code) to make sure the project includes a user manual. Because if this doesn't happen, it only fosters the next problem - laziness.

There is a vicious circle going on with regards to Linux documentation. A developer fails to write proper documentation, forcing users to resort to googling their problems. Thanks to Google, the users (at least those who understand how to "google a problem") are typically sent to forums where others have had the same problem. Thus, through a community-like, drawn-out effort, the problem is (hopefully) solved. Because the users are getting the software working, the absence of documentation is not so much an issue - at least not to the developer. So the developers become lazy.

For this, I have a suggestion that (although it might ruffle some feathers) could solve this issue.

I believe there needs to be some sort of peer review process before an application is accepted into a repository. This process could be simple:

  • Ensure it adheres to the GPL (unless it is placed into the "Commercial" category that might soon hit the Ubuntu Software Center).
  • Ensure the software includes documentation.
  • Ensure the software works as expected.

I understand that what I am suggesting could be one heck of an overwhelming task, but I believe it is one that could mean the difference between vast Linux adoption and moderate Linux adoption. But there is another issue brought about by the fact that Linux itself (not just the applications) needs better documentation. In fact I believe the landscape of the Linux documentation needs to look like this:

  • Linux operating system fundamentals
  • Kernel documentation
  • Sub-system documentation (such as printing and sound)
  • Desktop environment documentation
  • Command-line documentation
  • End-user application documentation

The above list would cover everything. Not all users would need all of the above documentation. In fact the majority of the documentation used would be:

  • End-user
  • Desktop environment

This would be quickly followed by:

  • Sub-system
  • Command line
You might think, upon first glance, that getting people to write the above documentation would be impossible. It's not. Much of it is already written (desktop environment documentation, command line man pages, etc). The big task is organizing it into such a form that is easily accessible to the end user and public in general. This could easily fall under the umbrella of the Linux Documentation Project. I can't think of a better location for the task. However, a governing body should step in to take this task over. The Linux Standards Base comes to mind.
Final thoughts
I might be crazy, but I think this could come to fruition if the right people took it on. The coordination of this effort might be fairly great, at first, but the payoff is well worth it. I have connections with the LSB; I might have to point them to this blog entry and get this ball rolling myself. With the right documentation, Linux' worst Achilles heel could be removed and our favorite operating system accepted en masse.


Jack Wallen is an award-winning writer for TechRepublic and He’s an avid promoter of open source and the voice of The Android Expert. For more news about Jack Wallen, visit his website

Editor's Picks