Re: [Cooker] bug-reporting FAQs (was: 9.1...Delayed)

2003-03-12 Thread Duncan
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)

2003-03-11 Thread Ben Reser
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)

2003-03-11 Thread Guillaume Cottenceau
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)

2003-03-10 Thread Ben Reser
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)

2003-03-10 Thread Jason Greenwood




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)

2003-03-10 Thread Ben Reser
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)

2003-03-07 Thread N Smethurst
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)

2003-03-07 Thread Guillaume Cottenceau
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)

2003-03-06 Thread Leon Brooks
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