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

[Dave Griffiths]

On Fri, 13 Aug 2004 12:54:19 +0200, Florian Schmidt wrote
> On Thu, 12 Aug 2004 09:13:02 -0400
> Dave Phillips <dlphilp at bright.net> wrote:
> 
> > 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.
> 
> I'm a big fan of wikis. They make it so easy for the user to contribute
> documentation. 

As a user of applications, I'm more than happy with:
1. Examples - nothing better IMHO
2. A wiki - user written/maintained docs are more valuable than programmer speak.

As a user of linux, alsa and jack I want something more formal, HOWTO's and
step by step walkthoughs of setting stuff up - with what to do if things go wrong.

As a developer I like wikis as they take some of the pain out of writing docs,
you can do it in a quick fluid way, and people can clarify and add their own
thoughts. If you want nice formatted final docs, these can be taken from the
wiki after things mature.

Also examples are very valuable to developers for regression testing.

Just my tuppence...

dave