Subject: Re: [linux-audio-user] some thoughts about Linux audio software documentation
From: Rick B (zajelo3_AT_cfl.rr.com)
Date: Fri Aug 13 2004 - 00:50:12 EEST
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
>
>
>
>
>
That is the state of most Linux documentation today, most of it is
out dated, and anyone who has used Linux for a time will realize that
anything older than 6 months *might* be wrong. It is easy to see where
the problem is within the Linux audio developers community, it is the
fact that most of the developers are coders as well as musicians, and
thus have their proverbial plate full with two very time consuming
pursuits, and have no time left to keep the documentation up to date.
The fact that the development process is so fast just compounds the problem.
The answer to the problem might be for the developers to have a book
(an indepth manual if you will) published for them, once the application
gets to a certian stage of maturity, that the public can buy. This would
also provide a means for the developers to allow the application to be
free, and still make a living. If a person doesn't wan't to buy the book
they don't have to, they are perfectly free to sort through the online
documentation. With other apps (cubase,protools,etc.) you have to buy
the app and the book.
Rick B
This archive was generated by hypermail 2b28 : Fri Aug 13 2004 - 00:49:32 EEST