[Fwd: Re: Triage guide...]

[Elijah Newren <newren math utah edu>]

I'm resending this to the list, because I believe Malcolm has good
pointers on how to write documentation that others may benefit from and
also provides some insights on the bugsquad itself.

-----Forwarded Message-----

From: Malcolm Tredinnick <malcolm commsecure com au>
To: newren math utah edu
Subject: Re: Triage guide...
Date: 04 May 2003 19:48:35 +1000

On Sun, May 04, 2003 at 11:44:15AM +1000, Malcolm Tredinnick wrote:
> On Sat, May 03, 2003 at 10:17:35AM -0600, Elijah P Newren wrote:
> > As aes suggested, I'm going to try to merge the current triage guide
> > with an extended one that I made
> > (www.math.utah.edu/~newren/howto-triage/).  However, I still haven't
> > gotten a whole lot of feedback on that guide.  I'm wondering if it's
> > because people don't like the overall one that I have (even if they
> > might like certain parts) and don't want to offend me.  Chickens.  I'm
> > only going to be offended if you tell me that my idea of making triage
> > examples are worthless (they're the main reason I wrote that page; and
> > I'm betting you won't say this since aes and aldug already told me they
> > liked them--or at least the idea of them), the other stuff I don't care
> > as much about.
> 
> OK, I'm as guilty as everybody else ... I have not read it. Will try to
> make time to do so today.

OK, I have read it now. Generally, an excellent document and I support
your efforts to merge it with Andrew's triage guide. The two documents
complement each other nicely.

I have a few comments, mostly editorial in nature...

- In the section about "What skills are needed in order to help triage
  bugs?", you might want to mention that another goal is seeing if some
  of the more dubious looking bugs are repeatable or not. That is
  something that anybody can usually do (unless it requires a specific
  network setup or something) and is of huge assistance to the
  developers (I will usually look a fixing a repeatable bug before one
  that look sporadic, just because it often affects more people).

- In "How long does it take to learn how to triage bugs?", you are in
  danger of scaring people off. It _may_ take them a couple of hours to
  go through your document in total, but that looks like an awfully big
  time commitment up front. Maybe reword the first paragraph in that
  section to say that it is not required to read the document all at
  once and it is designed to be referred back to. The second paragraph
  there is fine, except that you use "over the learning curve" again and
  the repitition jars with paragraph one (and using contractions like
  "you've" in written work is usually to be avoided).

- If the #bugs channel has people in it all the time, can you mention
  that (hmmm .. spot the person who nevers visits #bugs :-( )? Also,
  maybe mention Bug Days a bit more explicitly -- a link to
  http://developer.gnome.org/projects/bugsquad/bugday.html, perhaps? The
  reason to repeat the information that #bugs is always available is
  because Bug Days are at a time that is not going to be convenient for
  a lot of people (because of timezones or work commitments), so they
  need an alternative interaction route.

- Maybe put the "Quick Note" portion of step 7 in the "How to get
  started" section in emphasis tags? Or make it a new paragraph, or
  both? Otherwise it tends to be hidden in the paragraph.

- I suspect it might read more nicely if you moved the expamples section
  to the very end (or maybe just before the list of "Important links").
  Aside from the examples, the rest of the document can just be read
  from beginning to end and contains useful information. The examples
  section is a bit more interactive and not very useful without the
  interaction component. So it interrupts the flow of the rest of the
  information for me.

> > Here's one area where I'm starting to think that my triage guide sucks. 
> > The majority of the people that decide to help out have at least some
> > kind of programming experience.  These people are definitely the most
> > able to help, yet my guide, since it was geared more towards people
> > without programming ability or computer knowledge, may turn them off
> > with the level of detail it has.  I was thinking of throwing almost all
> > of my extra stuff into a well organized FAQ and then adding "(See also
> > FAQ B-13)" or "(See also FAQs #2 and #8)" throughout a streamlined
> > simplified guide.  [Of course, some FAQs wouldn't be referenced and are
> > simply in the FAQ for more information].  This would also make it really
> > easy for us to answer people's questions on IRC ("Look at FAQ C-2").
> > 
> > Does this sound reasonable?  Other pointers/ideas/suggestions/gripes?
> 
> Well, things like bug-days are often aimed at non-developers.  Bug
> triaging is one of the areas we regularly encourage people who are not
> willing to be hackers to contriute to. So however you structure the
> document, I think a reasonable level of basic information should remain.
> I think you are misassessing the audience here.

Now that I have read the document while paying attention, I will stand
by the paragraph I wrote above. I do not think your article spends too
much time on the fine details. A more experienced person will realise
they can gloss over the step-by-step sections that seem too "slow" for
them. With the exception of the "Quick Note" in step 7, if somebody
glossed over the entire "How to get started" section, only noting the
links (which are highlighted anyway), they would not lose critical
information.

If you have lots of small steps in any portion of a document and
somebody starts to skim, you generally lose their attention until the
end of that section. However, something like the "Special notes" section
is not long enough that somebody's mind is going to wander before they
finish it and each point is sufficiently different that they will stay
interested. So I would keep the "getting started" section as is, but
highlight the "Quick Note" as mentioned above so that people spot it on
a quick scan and be sure that if somebody did just read the initial
sentence in each step in that section they are not missing anything too
important. That way, conscientious people and beginners will read all of
the steps (as is appropriate for them) and more confident people may
just skim that section, but will not miss anything too valuable if they
note the highlighted bits in passing. I think that works around the
concerns you mention above.

I hope this mail does not come across as too critical. It is a nice
piece of work and I can appreciate the time you have put into it so far.

Cheers,
Malcolm

-- 
Two wrongs are only the beginning.