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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Thu, 2004-08-12 at 15:59, 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,
> 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

The documentation by noobs is a great concept! And not only that, the
"noob" learns in the process.  

So I *should* get busy and write that "live fx box How not to" huh?! :)
I can write a thesis on what NOT to do! 

R~
> 
> 
> 
>  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
> > > 
> > > 
> > > 
> > > 
> > 
> 


[Index of Archives]     [Linux Sound]     [ALSA Users]     [Pulse Audio]     [ALSA Devel]     [Sox Users]     [Linux Media]     [Kernel]     [Photo Sharing]     [Gimp]     [Yosemite News]     [Linux Media]

  Powered by Linux