Subject: X Documentation that doesn't suck
From: Patrick Callahan (pac1@tiac.net)
Date: Sun Nov 18 2001 - 09:00:25 MST
John,
I've read your November 3rd post on YellowDog Linux about Linux Documentation
and one of the responses.
I too feel that the quality of linux documentation is far lower than most
linux partisans are willing to admit. I find much of it fragemented, uneven,
of limited usefulness, especially when you compare it with the best
professionally written software and its documentation. I don't say this to
disparage linux or the existing documentation. Linux is truly an
achievement. It does work. It is useful and with the right set of knowlege
and strategies the documentation can be used as it stands to do useful work.
I think the main problem is that a lot of linux/gnu documentation is written
as a description of individual programs, not as a tool for usage of software.
A perfect example of this are the man pages. Most of them include
absolutely no examples whatsoever. There are few clues in the man pages of
how each command fits into a larger whole.
The hype tells you there's millions of people "working in open source"
I think that the actual numbers are quite small. The actual number is
thousands not millions. Has anyone done a census?
How do we get to documentation that doesn't suck? I don't know, but I'm
certain some central mechanism for guiding the process with a clear set of
documentation principles is needed. The governance we see in use today
covering the documentation being produced just doesn't cut it. Most of the
standards for documentation covers formatting and processing. While that's
obviously necessary, the principles that govern the content itself are
un-examined and as a result the documentation is often fragmented and
incomplete.
Documentation used to be divided into "Reference Manuals" and "User Guides"
What's most often missing in Linux Documentation are the "User Guides". Much
of the recent work of the Linux Documentation project has been focused in
this much needed area.
I followed the Linux Documentation project for a while, but they were at the
time very focused on just producing specific documentation and standardizing
the production and formatting process. They've done an excellent job with
that and have produced some good and very useful work. Their standards for
document preparation are a necessary piece of the puzzle. Still I think
there's something missing.
I think one thing that's missing is documentation that focuses on usage
rather than structure of the program. We need additional documentation that
focuses on the why and how more than on the what and where. Don't
misunderstand me on this point. We'll still very much need the documentation
of the what and where.
You've been having trouble with X. So have lots of others. The
documentation that would allow us to use X simply and effectively does not
seem to exist. Yet... I'm trying to find or create X documentation that
effectively tells what all its pieces are, how they're related and how the
entires in the configuration files are actually used.
Care to join me in this? Wanna read code?
Pat Callahan
Acton Ma
P.S. Norair, Have you gotten that problem with the "missing" display fixed
yet?
This archive was generated by hypermail 2a24 : Sun Nov 18 2001 - 09:13:00 MST