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

[Mark Knecht]

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 ?
> 
> Best regards,
> 
> dp
> 

Dave,
    There is NOTHING worse than wrong documentation. It's far better to 
have NO documents than ones filled with incorrect stuff. At least then 
you know you need to ask for help instead of wasting hours/days/weeks, 
and in my case, months, thinking that the problem is mine when it wasn't.

- Mark