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

[LinuxMedia]

dlphilp at bright.net wrote:

> Recently I received a letter from a
 > fellow who civilly noted how atrocious
 > is so much of the documentation for Linux
 > audio software...

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


>  Any comments ? Any takers ? Does anyone care ?

Oh boy... were to start?

First... thanks for all you've done for the linux/audio community. I 
know I've benifited from good documentaion that you've written.

I saw this post and was on my 15th hour in front of my computer. I 
decided to sleep on it and then when I got up, I went to the Linux 
Documentation Project to see what I may be able to contribute.

The LDP just varified what had been slowly brewing in my mind. Sure, 
you, I and other's can write a How-To and there would be one more How-To 
that is up to date. So that stands on it's own. Yet, things change all 
the time. I've sat and (with great enthusiasm) went to write a "quick 
start" guide to one of my favorite apps. But then it was either 
discontinued, or there became a different approach that was more in line 
with the "future of linux/audio".

I think that what I may be able to offer is a suggestion of what I'm 
actually doing. Yes... contribute something (if you can). But also... 
take the time to put together a great recording environment and go out 
and *actually* set up linux boxes for people. That's what I plan on 
doing. But *only* do it if you think you can actually show people how to 
run things correctly. That means making sure you did your homework and 
made things "usable". No "end user" is going to go into a shell and type 
aconnect -i to find the correct midi ports (let alone issues commands to 
connect them).

I guess I'm coming to the conclusion that linux/audio is (currently) not 
meant for the end user. And that's what I "bought into" when I made the 
decision to work with the linux platform (let alone with my focus being 
on audio from a community that's constantly developing).

I wanted to be able to say "I'm here... how do you want me to 
contribute". But it just seems too big. I'll write a How-To and it will 
be out of date. And of course there would be one more up to date How-To 
for *a while*. But what about when that gets out of date?

It's ironic that I'm communicating these things *here*, because it seems 
(to me) that if anyone is serious about working with such a (what's the 
word?... grass-roots?... devloping?... maverick?) community like 
linux/audio, then they go thru the trouble of sighing up for mail list 
like LAU and reading daily post (and actually trying the things they are 
reading). Linux audio (currently) isn't a "hobby" or "faint endevor" for 
me... it's a lifestyle. A lifestyle that means I accept that (someday) I 
will have a great set-up I will be able to duplicate for the musicians 
around me.

I'm not trying to make excuses or "bow out". I don't believe in talk 
without action. It's just that there's way too many things that I'm 
trying to get together (so that) I can acutally sit with a local 
musician friend and show them (in person) how to (actually) use the 
software that I (just) installed on their machine.

I wish I had something more concrete to offer. I'm just busy as trying 
to create the template that I will eventually set up for others. And 
that means (not only) a great (audio) set up, but having a useable 
"upgrade" set up. That means making sure they can connect to the 
internet to get new samples as I discover more... having the window 
manager set up so it easy to navigate. These are only *two* of many, 
many issues I'm dealing with so that I can contribute in a more direct 
way (setting up computers).

I appoligize for the long email. It's just that Linux/Audio is such a 
huge and ever-changing thing, that my explaination had to reflect the 
situation.

Rocco