The Documentation Problem
Measured by sheer volume,
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
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,
These are all reasonable places to look;
why is it that none of them
contains a See Also reference to the others?
although Perl has a fine
as well as some handy file test operators,
I won't find them listed as first-class citizens
Rather, they are hidden down
well out of the reach of
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