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: Dave Griffiths (dave_AT_pawfal.org)
Date: Fri Aug 13 2004 - 14:19:41 EEST


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


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

This archive was generated by hypermail 2b28 : Fri Aug 13 2004 - 14:22:36 EEST