Subject: Re: [linux-audio-user] some thoughts about Linux audio software documentation
From: tim hall (tech_AT_glastonburymusic.org.uk)
Date: Fri Aug 13 2004 - 02:41:15 EEST
Last Thursday 12 August 2004 23:05, Lee Revell was like:
> On Thu, 2004-08-12 at 17:50, Rick B wrote:
> > Dave Phillips wrote:
> >
> > That is the state of most Linux documentation today, most of it is
> > out dated, and anyone who has used Linux for a time will realize that
> > anything older than 6 months *might* be wrong. It is easy to see where
> > the problem is within the Linux audio developers community, it is the
> > fact that most of the developers are coders as well as musicians, and
> > thus have their proverbial plate full with two very time consuming
> > pursuits, and have no time left to keep the documentation up to date.
> > The fact that the development process is so fast just compounds the
> > problem. The answer to the problem might be for the developers to have a
> > book (an indepth manual if you will) published for them, once the
> > application gets to a certian stage of maturity, that the public can buy.
> > This would also provide a means for the developers to allow the
> > application to be free, and still make a living. If a person doesn't
> > wan't to buy the book they don't have to, they are perfectly free to sort
> > through the online documentation. With other apps (cubase,protools,etc.)
> > you have to buy the app and the book.
>
> What is needed is for non-coders who understand the apps to write the
> documentation, "power users" in the Windows-speak (I always hated the
> term). The developers are glad to help you if you have a question like
> "I am writing some docs for $FOO, why does it do $BAR, and what is the
> $BAZ menu for?". This is a great way for non-coders to contribute to
> open source.
What Dave says about the length of time it takes to gain a working familiarity
with the application you're trying to document is relevant here, having
seriously considered the issue. In the long term, I'd like to contribute in
this way, I know I'm capable of writing procedural documentation but as yet
I'm expert at very little of the software and life has a way of keeping me
busy, so I can't promise much.
> The problem is there are a lot more people willing to write code for
> free than write user documentation for free. Many developers are not
> native English speakers, so in many cases it is much harder to write
> good English user docs than write code! Developer documentation is much
> easier because there is already a common language.
I'd be happy to proof read / ghost write any such documentation if the basic
information is already there and just needs pulling into shape.
> If you are a user willing to contribute documentation, the developers
> will bend over backwards to help you, because good user documentation
> equals fewer spurious bug reports and happier users.
Well, this is my first attempt:
http://wiki.agnula.org/wiki/wiki.phtml?title=DeMuDi-config-HOWTO
cheers
tim hall
This archive was generated by hypermail 2b28 : Fri Aug 13 2004 - 02:44:43 EEST