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

[John Check]

On Thursday 12 August 2004 05:50 pm, Rick B wrote:
> 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.

And that's precisely why we have to consider developers for whom coding isn't 
a primary skill. If we can make things more attractive for people who can 
build and test things without side tracking them, we would have a bigger pool 
of documentation maintainers.
 
Here's some anecdotal experience: One day I wanted to sequence orchestrations
for "Kashmir". I found an appropriate package, but it had a bug that nobody 
caught because it wasn't completely tested, solely because the developer pool 
is tiny (It works for me!). 
Long story short, two weeks later, after having to do unnecessary system 
upgrades (on Debian unstable, no less) and tracking down and supplying a 
workaround for the bug, I finally remembered that I was trying to do an 
orchestration.
I would have much rather spent the two weeks using the program and documenting
it. 
Yes, it would have been better if I'd had the skill to fix the bug properly 
instead of supplying a workaround, but the best thing would have been for the 
bug to have caught in testing and fixed properly by somebody who's a coder.


> 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.

My feeling is that it's not realistic to expect coders to write user 
documentation, so that's not what I'm saying by any definition.

> 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

Oh, the irony. You do realize that the book will be pirated, right? There is a 
way to make a living at this, and it's based on cooperation and respect.
They call it "pro audio" because there's plenty of money being spent. 
We're not going to dry up that money ever, so the best thing to do is think 
about how do we channel that into R&D funding for the guys doing the heavy 
lifting. 
The _real_ impact we can have is closing the gap between "pro" and "schmoe"

> 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.
>

Last piece of music software I bought was Vision, and that came with a manual.
If the situation changed since then and it's indeed two separate purchases, 
it's got to be because the vendors are milking the customers. That's 
something else we can fix.


>                 Rick B