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

[Lee Revell]

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.

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.

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.

Lee