[linux-audio-user] some thoughts about Linux audio software documentation

[John Check]

On Thursday 12 August 2004 09:13 am, Dave Phillips wrote:
> Greetings:
>
>   Recently I received a letter from a fellow who civilly noted how
> atrocious is so much of the documentation for Linux audio software.
> While that may be generally true it is also easy to point out specific
> excellent docos, e.g., Snd, Csound, LilyPond, Rosegarden, etc., though
> too at the same time it must be admitted that even those docs are not
> necessarily the most well-organized. Perhaps this fellow's most damning
> statement was made re: the HOWTOs available from the Linux Documentation
> Project (LDP). I decided to check out the situation myself, and here's
> what I found (the doc is followed by its last revision date):
>
> Linux Sound HOWTO   July 2001
> ALSA Sound mini-HOWTO    November 1999
> Linux MIDI HOWTO    May 2002
> Linux MP3 HOWTO   December 2001
>
>   Worse, the LDP's own documentation refers back to these out-of-date
> pieces, making sure that readers continue to be misinformed. I mean no
> critique of the excellent LPD, but it seems to me that as a community we
> have an obligation to correct this situation. For all the talk about
> improving documentation, here's a chance for anyone to get directly
> involved. The format for these HOWTOs is simple and already laid out:
> what's needed is currency, someone to correct and update the basic sound
> & music oriented HOWTOs. Otherwise it might be better if we asked the
> LDP to remove the docs in order to mitigate confusion.
>
>   Any comments ? Any takers ? Does anyone care ?
>

I do. It's a very time consuming job though and I have some ideas for 
improvements to the process.