Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
On Mon 10 Mar 2003 19:26, Ben Reser posted as excerpted below: > 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. I've thought about this b4, re other projects.. If I was a web page coder, it wouldn't be to hard to take copies of my posts to the newsgroups or mailing lists and redo them a bit, to post on the web, with a URL attached that I could reply with, instead of repeating the same several hundred line explanation over and over... Here, that's always been in the "it'd be nice if.." category and I've never gotten around to it. However, one regular on an ISP's DSL group that I used to hang out in did just that, taking his material, mine, and that of another regular that helped in the group, edited them a bit, and posted them on his site. The site quickly became an oft cited reference both for us in the group, and for the ISP tech help as well. (FWIW, the ISP was uswest.net, the group uswest.dsl, and the author Randy Lutton. The site was part of his home page. USWest.net is now Qwest.net, but I just checked, and the site is still there, at http://www.users.qwest.net/~rlutton/ADSL/ -- note that the ADSL must be in caps.) I did, at one point, create a boiler-plate answer that I could cut and paste, for a couple of questions, but that's as far as I ever got.. -- Duncan "They that can give up essential liberty to obtain a little temporary safety, deserve neither liberty nor safety." -- Benjamin Franklin
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
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
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
Ben Reser <[EMAIL PROTECTED]> writes: > On Fri, Mar 07, 2003 at 12:56:21PM +0100, Guillaume Cottenceau wrote: > > I'm personally skeptical about FAQ's and such documentation, > > because so many people plain ignore documentation in favor of > > asking questions (many different projects of mine show). You know > > that I've even written the cooker-FAQ and maintained the mdk-rpm > > howto, so I guess I can voice up :). > > This is faulty logic. You are assuming that because some people refuse > to read documentation that all people do. That's just not reality. The > Mandrake RPM Howto is an invaluable resource. I use it on a regular > basis. I direct people to it on a regular basis. It would be far more > useful if it was kept current and included details on things like > mklibname etc... > > 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. I agree on the fundamentals of your reasoning. I'm just a bit "tired" because of much recurrent questions, but of course you're right. -- Guillaume Cottenceau - http://people.mandrakesoft.com/~gc/
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
On Tue, Mar 11, 2003 at 03:37:33PM +1300, Jason Greenwood wrote: > However, the newbie and expert lists help alleviate this by recycling > the knowlege passed down from developers and Mandrake itself. Sometimes, > a little encouragement from a fellow user goes a long way too IMHO. But that is entirely a separate issue. At least among those of us that contribute and the developers. Every minute we spend explain some long standing policy, closing a bug, etc... is time we aren't spending on fixing bugs and implementing new features. -- 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
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
However, the newbie and expert lists help alleviate this by recycling the knowlege passed down from developers and Mandrake itself. Sometimes, a little encouragement from a fellow user goes a long way too IMHO. Ben Reser wrote: On Fri, Mar 07, 2003 at 12:56:21PM +0100, Guillaume Cottenceau wrote: I'm personally skeptical about FAQ's and such documentation, because so many people plain ignore documentation in favor of asking questions (many different projects of mine show). You know that I've even written the cooker-FAQ and maintained the mdk-rpm howto, so I guess I can voice up :). This is faulty logic. You are assuming that because some people refuse to read documentation that all people do. That's just not reality. The Mandrake RPM Howto is an invaluable resource. I use it on a regular basis. I direct people to it on a regular basis. It would be far more useful if it was kept current and included details on things like mklibname etc... 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.
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
On Fri, Mar 07, 2003 at 12:56:21PM +0100, Guillaume Cottenceau wrote: > I'm personally skeptical about FAQ's and such documentation, > because so many people plain ignore documentation in favor of > asking questions (many different projects of mine show). You know > that I've even written the cooker-FAQ and maintained the mdk-rpm > howto, so I guess I can voice up :). This is faulty logic. You are assuming that because some people refuse to read documentation that all people do. That's just not reality. The Mandrake RPM Howto is an invaluable resource. I use it on a regular basis. I direct people to it on a regular basis. It would be far more useful if it was kept current and included details on things like mklibname etc... 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. -- 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
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
Le Vendredi 7 Mars 2003 12:56, Guillaume Cottenceau a écrit : > I'm personally skeptical about FAQ's and such documentation, > because so many people plain ignore documentation in favor of > asking questions (many different projects of mine show). You know > that I've even written the cooker-FAQ and maintained the mdk-rpm > howto, so I guess I can voice up :). The problem is perhaps not that there is no documentation, but that the existing documentation relevant for would-be bug testers is not presented in a unified fashion or in the most appropriate locations (i.e. a link from the front page of Bugzilla would be one obvious choice).
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
Leon Brooks <[EMAIL PROTECTED]> writes: > On Thursday 06 March 2003 11:47 pm, Guillaume Cottenceau wrote: > > For install problems, many of them are duplicate: some we set as > > duplicate, some we ignore; many don't provide enough information, > > some of them we ask info some we ignore because we suppose it > > would cost too much time to get the information; many are non > > important or design issues, we don't have time to explain each > > and every minor/design point; many of them are already fixed. > > How about, perhaps post 9.1 although it would be really nice just now, a > two-page installer-bug-reporting FAQ and another general bug-reporting FAQ > with these and like questions on? I'm personally skeptical about FAQ's and such documentation, because so many people plain ignore documentation in favor of asking questions (many different projects of mine show). You know that I've even written the cooker-FAQ and maintained the mdk-rpm howto, so I guess I can voice up :). -- Guillaume Cottenceau - http://people.mandrakesoft.com/~gc/
Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)
On Thursday 06 March 2003 11:47 pm, Guillaume Cottenceau wrote: > For install problems, many of them are duplicate: some we set as > duplicate, some we ignore; many don't provide enough information, > some of them we ask info some we ignore because we suppose it > would cost too much time to get the information; many are non > important or design issues, we don't have time to explain each > and every minor/design point; many of them are already fixed. How about, perhaps post 9.1 although it would be really nice just now, a two-page installer-bug-reporting FAQ and another general bug-reporting FAQ with these and like questions on? With the list running at near a thousand messages a day as it is now, posting a URL for those pages daily is not out of order, otherwise once a week. Cheers; Leon