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

New Message Reply About this list Date view Thread view Subject view Author view Other groups

Subject: Re: [linux-audio-user] some thoughts about Linux audio software documentation
From: John Check (j4strngs_AT_bitless.net)
Date: Sat Aug 14 2004 - 01:26:23 EEST


On Thursday 12 August 2004 06:59 pm, Jan Depner wrote:
> When I started using Linux for audio a few years back (I started using
> it for other things in 1993) I found Ardour to be the main application
> that I wanted to use. Since I didn't think that I could spin up to help
> with the software in a short period of time I decided to help in another
> way - I wrote my own documentation on how to install it. I then started
> writing what little bit of user documentation that I could (later Paul
> asked that we all stop with the documentation). That was my first
> contribution to Linux Audio. More recently I've been working on JAMin
> and doing the install and user docs for that. I tend to agree with PJ
> (Groklaw) - documentation should be written by newbies because the
> authors are usually too close to the apps and are too familiar with them
> (it should be intuitively obvious to the most casual observer...). So,

Everybody knows you gotta turn the mixer up *cough*ALSA*cough* ;)
There's a bit of chicken and egg there scope-wise with regard to newbs writing
doco. It's not a panacea, but it's an important part of a balanced set of
doco.

> how about some of the users start in with documenting how they use the
> apps, what problems they had, or anything else that might help? If
> you've got anything to add to the JAMin docs (that I missed because it
> was intuitively obvious ;-) send it to me and I'll try to add it to the
> web pages.
>
> Jan
>
> On Thu, 2004-08-12 at 09:58, 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?
> >
> > 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...
> >
> > {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


New Message Reply About this list Date view Thread view Subject view Author view Other groups

This archive was generated by hypermail 2b28 : Sat Aug 14 2004 - 01:28:32 EEST