On Thursday 12 August 2004 06:05 pm, Lee Revell wrote: > 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. Precisely. > > 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
