The Soap Box - Opinion

by Eb Guenther

Help Files and Other Useless Documentation

Despite the title, there are many software applications with useful help files. The unsung heroes.

As usual, it’s the squeaky wheel that gets the grease. If your help file or documentation does not fall into any of the categories below, more power to you! But if it does, I hope I have provided a few hints on how you could improve your user support.

Time and again I have popped open the help file from an application, looking for an answer to a burning question about how to do something in the application, only to discover that I was asking about problems the author did not anticipate. Or I tried the so called “FAQ” (frequently asked questions), only to discover that the questions were written by marketing drips, as a wrapper for some hype they wanted to get across to an already sold consumer. Sort of like the Jeopardy TV quiz show, these “questions” were created after the “answers”. That is not what “FAQ” implies.

Some software publishers have found more idiotic ways to showcase their (lack of) intelligence. Have you ever downloaded a compressed software package, put it into a folder, and forgotten it for a while? Have you come back to the file a month or so later, unzipped it, only to discover that there was no clue in the file, even hinting at the purpose of the software? Happens to me all the time. I live in the boondocks, so I have to drive a ways to get to a broadband connection, which I use to download stuff, burn my downloads to a CD, and maybe get around to checking the CD a week or two later. Under those conditions I don’t have time to check out whether I want something or not. It’s easier to just download it. If a download turns out to be something I need, I’ll try it out. But if I look at the content of a zip file, and there is no readme file or other information file that tells me what this “thing” does, it gets trashed. The author has lost my custom. Although if I did run across the same file again, I would probably not recognize it, and go through the same cycle again. Apparently, these authors use acronyms, that to them describes the product, never mind, that acronyms mean different things, depending on your point of view.

Consider “ATA”. The general public probably thinks it stands for Automatic Teller Machine. No, no, say the computer hardware people. It stands for AT Attachment, a disk interface. Some computer guys might even interpret ATA as a modem command. Members of the American Toilet Association quietly chuckle as they voice their own take on this situation: “FluTIALoWaTWa” (Flush twice, it’s a long way to Washington).

If you get the idea that missing documentation is the worst that could happen, consider documentation with an attitude! The author assumed that only rocket scientists would need documentation. All others would automatically know how to use the application, and not need to refer to the docs. Consequently, you better be a rocket scientist if you want to understand that manual. Is it just me, or is this bass-ackwards? These kind of docs contribute little but bulk to the distribution. Perhaps they were afraid that the CD-ROM would fly away without the extra weight?

Then there is “echo documentation”. This can either be an auto-generated help system identical to the manual, or to the menu structure, or vice versa. There you are, having read the so-so manual, loaded the application that you were curious enough to try out, and a question comes up. The help system is extensive, but strangely familiar. You type a keyword you remember having seen in the manual into the help index. Hmm, not there. You try the search mode. A screen pops up with little information, other than what you had already read in the manual (verbatim, but strangely unsatisfying, because it does not explain anything). You think you’ve seen it all, then you run across a notice in the echoed manual that refers you to the online help. Yup, you guessed it. The help system also has that notice, “for more information, please refer to the Help system.”

Help files should support manuals, not echo them. Most of all, though, help files should not echo the menus! Some diseased software authors simply load the software code into an editor, strip the code and comments, and leave the menu structure as the help system. For example, you are in a “Tools” menu with 3 choices: “Properties”, “Insert”, and “Rename”. You click on the context-sensitive help icon (the question mark with a pointer), and point to the “Insert” option, and click. A pop-up window proclaims “choose a file to insert”. When you click on the option directly, you get a pop-up window labeled “choose a file to insert”, and a browse button. Has this ever happened to you?

Finally there is the over-abundance of documentation. This seems to be limited to Unix-like open source operating systems. I came across an extreme case, researching a Linux article series. Linux has everything documented. That would seem to be a desirable state, except there are four or five versions of documentation sets. One gets the impression that every contributor to the Linux project has at one time or another written his or her own documentations. I downloaded four sets of different Linux documentation, and discovered a fifth — the infamous “man pages” (as in “read the man pages”) — in the Linux distribution. The stuff I downloaded takes up 100 MB of disk space, not counting the man pages.

There are Introductions to Linux, HOWTO guides, miniHOWTO guides, unmaintainedHOWTO guides, plain text versions of various documentations, HTML versions of vendor specific manuals and PDF versions of those manuals. And of course, there are the man pages, in Unix format and html format. I would like to add, that the PDF manuals for Red Hat Linux 9 are well worth downloading. I use the man pages only for those utilities not covered by the PDF files.

By the way, the HOWTO files seem to be contests in maximizing the number of files these HOWTOs can be written in. I have encountered several files, whose only information was a link to another HOWTO file.

Eb Guenther can be reached at

E-mail me at with any comments you have and tell me what you want to see here.

Back to the Magazine Home Page

Last modified: 2003:08:22