Re: X Documentation that doesn't suck


Subject: Re: X Documentation that doesn't suck
From: John Norair (jnorair@Princeton.EDU)
Date: Sun Nov 18 2001 - 12:43:45 MST


I'd love to help, but I really have no time in my schedule to fit in
something new. I have made a little progress on the X display issues,
but I really need a week or two off in order to really get cranking.

Thanks for the friendly advice,
John Norair

> eel 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 - 12:58:51 MST