On Mon, Mar 10, 2003 at 06:26:36PM -0800, Ben Reser wrote: > Fact is the documentation does decrease questions. But it will never > eliminate them entirely. It would be much easier if when people asked > commonly asked questions we could direct them to concisely written > documents, rather than typing the answers out again over and over and > over again. > > The amount of time spent producing the documentation would likely be > paid off in the savings of time of people responding to these questions > and in simply better quality output by those of us who do spend the time > reading them.
Couple more thoughts on this that I've had... Bad docs bread an environment of not bothering to look at the docs. If a user knows there is a likelyhood that the docs are incorrect or outdated they will often just ask. In some ways I'd say having poorly maintained docs is almost worse than not having any at all. Because then when you do update them you don't get the benefit of them as quickly, because you have to "re-educate" everyone that they should be looking ath the documentation. The other thought is that documentation provides lesser experienced people the ability to help the people who don't read the docs. When a person posts a message about something or asks on IRC there are generally many people who might not know the answer to their question. With documentation that is good and it's location known... Many of these lesser experienced people will be able to find the answer quickly and eliviate the load on the people that just know it in their head. Basically the documentation creates a larger pool of people to respond and answer the question. Plus if the documentation is normally very inclusive the less experienced person may just point the person there blindly say "I'm pretty sure that will be covered here..." This is the ideal solution as it teaches the person who is asking where to find information on their own (which they hopefully, though not always, will use in the future). Finally, poor documentation frustrates the experienced users. The very people you want. The people who do read the docs. Who can often times become your biggest evangelists or your biggest critic. The documentation is your chance to shine. Many of the best features of Mandrake Linux are poorly documented or not documented at all. urpmi is a perfect example (yes I know it has a man page, but I've run into a couple times when something just flat out wasn't in the man page or poorly explained, no I don't remember what at the moment.) Lack of authoratative documentation creates arguments which chews up everyones time. Let's face it. When there is a well written and thought out explanation of why things are the way they are, people are far less likely to needlessly argue about the policy. That's not to say that nobody ever will. It just means it heads off debate. Many times when someone asks a question all they get is the answer not the reason why. When they get pointed to the docs they are far more likely to hear why... Or at least if the docs are good they should. I honestly think documentation can make or break a project. Especially a large project that is open. When people don't understand policies and procedures it creates needless complications. I hope the attempts to produce some documentation suceed. -- Ben Reser <[EMAIL PROTECTED]> http://ben.reser.org "America does not go abroad in search of monsters to destroy. She is the well-wisher to the freedom and independence of all. She is the champion only of her own." -- John Quincy Adams, July 4th, 1821
