The Documentation Problem

Measured by sheer volume, Eclectic Systems are superbly documented. We have a wealth of online and printed documentation. Unfortunately, sheer volume isn't everything or even (really) enough. If administrators, programmers, or users can't find the information they want, in a reasonable period of time, the documentation isn't doing its job. And, to a large degree, it isn't.

The reason, in a nutshell, is lack of integration. Although individual documentation sets (e.g., man pages, the perlinfo suite) may be reasonably well integrated, the entirety is not.

To take a simple example, consider the problem of finding out the contents of an inode. On my FreeBSD system, I find man pages for inode(5), ls(1), and stat(2). These are all reasonable places to look; why is it that none of them contains a See Also reference to the others?

More generally, although Perl has a fine stat function, as well as some handy file test operators, I won't find them listed as first-class citizens in the man pages. Rather, they are hidden down in the perlfunc(1) page, well out of the reach of apropos(1).

Multiply this by dozens of languages and hundreds of tools and you begin to see the problem. In order to find the information I need, I have to know which documentation subsystem to ask. This, in a word, is broken. I shouldn't have to know where information is located in order to find it; that's what computers are for!

The situation gets even worse when we move away from indexed documentation subsystems. I wouldn't expect a book or magazine to have an online keyword index (though that isn't such a bad idea!), but what about the research papers and other documents that accompany software packages?

Far from being indexed online, these documents are very seldom mentioned in the online documentation. Worse, they may be in any of a variety of formats, forcing the user to hunt for (and perhaps acquire) the appropriate formatting tool(s), just to see if the paper is actually useful.

"Information delayed is information denied" (or some such sweeping assertion :-). If it takes too much time and effort to find the information I need, I might as well not have it at all.

-- Main.RichMorin - 16 Jun 2003
Topic revision: r5 - 08 Jun 2003, WikiGuest
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email