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

[John Check]

On Thursday 12 August 2004 10:58 am, Russell Hanaghan wrote:
> I care Dammit!  :)
>
> I think this is a valid point {& click).
>
> As a relative greeny to most things linux, I have found the vortex of
> info out there on some apps to be a show stopper many times. And then on
> ones that do have documentation...does it tell me the things need to
> actually know to make the software work?
>

Ah, synchronicity.

> It seems that most that can write code or develop applications aim at an
> audience that should "understand where to look for a problem" and while
> that's all okey dokey, especially since they ARE doing it for free in
> most cases, it does not speak to attracting the masses to what has
> become a formidable adversary to MS in more ways than just server
> application! {at least that's what my ignorant perception of Linux was}
>
> The forums and wikis are good...they help a lot. And folks in general
> are just so very cool about helping. {quote: Jack_fst for e.g....not to
> mention dozens of other things I got help with here for other stuff) but
> they don't cover everything by a long shot. Sometimes I wont ask on here
> because humble is not my best suite! :) And I can't figure it out in
> many cases so It don't get to work! Who knows if that piece of software
> wouldn't have changed the world!!! :) Or at the least, it might have
> changed my world! And frankly many of these linux audio apps have done
> just that...rock my freakin' world at a great rate of knots! And I get
> out and gig at least a couple of times a month and get a LOT of interest
> over the PC stuff...I have the best seat in the house to push this out
> there...but we can make their journey easier today...

Oh boy - get ready for the shit storm....

All pronouns are in the editorial sense.

Before anybody jumps on me, they should take a deep breath, put aside their 
pride and seriously consider what I'm about to say instead of just reacting.

One act gigging with this stuff is worth a dozen coders when it comes to
legitimizing the platform. There's so much potential with what's here today
that it blows my mind, but if it's "by geeks, for geeks" it really limits were 
we can go. There are some very fine pieces of free audio software now, but
the S/N ratio of good to not good would have made TA Edison grimace.

All you have to do is consider how much time it takes to evaluate
a package coming out of CVS vs studio rates vs cost to do it with commercial 
software to see what I mean. 
Did somebody say "Use an audio distro"? I say "That's a good start, but not 
all the programs are up to date, so if something looks potentially 
interesting but it's stale and buggy, one has to look at the project 
site/Wiki/lists and doco before deciding to build from source and even @ 
$30/hr it's cheaper to buy a Dell and get cakewalk bundled. 
Sure, a high end studio isn't going to use that, but high end studios, or even 
small fulltime going facilities aren't going to use anything free. Why?
When it comes to cost, you can't write off "free", or a programmers salary on 
you taxes (and studios need programmers like programmers need consoles), but 
you can write off much of the cost of say, a ProTools set up. Competing on 
price alone isn't enough. 
The upshot of this is there is a potential R&D funding bonanza that not too 
many people seem to be aware of. 

Okay, I've got things to do but I'd appreciate any feedback (DOH!) on this 
being well considered and objective. I'd rather spend the energy making the 
situation better, so consider these words in the spirit which I offer them, 
which is positive. 

>
> {quote: "ah grasshopper, when you have crossed the rice paper without
> tearing it you will have learned" unquote}
>
> On Thu, 2004-08-12 at 06:13, 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