13 Aug
2004
13 Aug
'04
8:11 p.m.
On Thursday 12 August 2004 06:05 pm, Lee Revell wrote:
On Thu, 2004-08-12 at 17:50, Rick B wrote:
Precisely.
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.
Anecdote: "The code is the best doco" - Saw some comments written in another
language, the translation was something along the lines of "this should work"
If you are a user willing to contribute documentation,
the developers
will bend over backwards to help you, because good user documentation
Not always true. You may have a system that's sufficiently different that they
can't help you or they may show a prejudice thats a turn off (say QT vs GTK)
when you ask question. Human nature and circumstance aren't negated by the
GPL. Last time I checked, coders were people too.
equals fewer spurious bug reports and happier users.
Absolutely. There's a conundrum there with regard to treating every user as a
documentation contributor though. Some users are just users and for them it's
tough shit.
Lee