Subject: Re: [linux-audio-user] some thoughts about Linux audio software documentation
From: John Check (j4strngs_AT_bitless.net)
Date: Sat Aug 14 2004 - 04:02:45 EEST
On Friday 13 August 2004 06:54 am, 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
I was a big fan of sniffing glue at one time ;)
> documentation. Have a look at alsa.opensrc.org. It surpasses the
> official alsa site in many places wrt the available
> information/documentation. And if it didn't it were a great addition
> anyways.
>
> So while i'm not saying that every open source project should use a wiki
> for their primary documentation site, they should definetly think about
> using a wiki as secondary more uptodate user contributed documentation
> source..
>
Actually, if that was the de facto standard way of doing things, the situation
would be a lot better than it currently is. Reality though? If I wanted to be
a jackass, I could go wipe out every wiki or plant bogus info. Would you
trust something that open for use with win32? Human nature.
> With some effort the rather wild and often unstructured collection of
> information that a wiki is can be refactored and flow back into the main
> doc.
>
That's the weakness - it's a crapshoot that this will be done. Otherwise
wiki is the proverbial tree falling in the woods.
> My suggestion would be: Transfer the above listed HOWTO's into wiki's
> and see what happens :)
>
"I fixed my problems by doing rm -rf / as root"
Seriously: Some sort of revision control with granular authorization and the
ability to tag things as SGML would be useful additions to wiki.
This archive was generated by hypermail 2b28 : Sat Aug 14 2004 - 04:08:09 EEST