Re: GNATS documentation evaluation

Subject: Re: GNATS documentation evaluation
From: Megan Golding <mgolding -at- secureworks -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: 30 Oct 2001 09:21:37 -0500

On Tue, 2001-10-30 at 08:03, Jim_McAward -at- Ademco -dot- com wrote:
> Our reviewers
> are not encouraged to exercise restraint with change requests, some do
> not
> speak English as their primary language, and sthose who are not well
> trained
> will issue bug reports on features that work as designed.

You mention a good point, Jim -- that without some sort of filter on
change requests they get too numerous to handle. However, isn't a change
request in a bug-report-format just as easy to handle as a marked up
hard copy? Ok, I'll concede that a bug report takes some additional time
in looking up the text.

My reviewers typically review electronic documents and when issuing bug
reports, they include the offending passage(s) in the report with a
context reference (in chapter 5, section 2, the third paragraph).

> However, bugs big and small both require the same amount of project
> leader
> intervention, and in the case of the documentation, all change requests
> must
> be accepted or rejected individually.

Yes, this is true. But, aren't you doing the same thing with a red-lined
hard copy when you "manually" reject changes. By tracking it in bug
tracking software, I mark those "invalid". The reviewer has a chance to
rebut my resolution...there is accountibility, in other words.

Oh yeah -- one huge advantage I've had in using bug tracking software is
that the number of "red-lines" for individual words or phrases has
pretty much gone away. Give a person a hard-copy, however, and all of
the sudden, they're your worst nightmare. "Change *this* word to *that*
word." Yuck! Since using bugzilla, my reviewers have stopped making such

> I'm not convinced this is an issue of organizational maturity (though
> Megan
> G. cites several good points). I think it is essentially a judgement
> issue
> (opinion vs. fact) on the part of the reviewers. Logging requests is
> fast,
> easy, and painless for the collective Them, and in our organization
> there is
> no penalty for late and/or meaningless requests - even though product
> cannot
> be released unless all the bugs/requests are resolved.

Maybe the issue is really one of "who is the reviewer?" When technical
types are doing the review (such as QA), I prefer bug reports. When
non-technical reviewers are doing the work, I prefer red-lined copies. I
have a reviewer in the marketing dept., for instance. I'd never ask her
to use the bug software -- too cumbersome.

Hmmm...I think Jeff is right - using bug tracking software for tracking
doc change requests isn't so much an issue of organizational maturity,
but one of type-of-review. Cool!



Megan Golding (mgolding -at- secureworks -dot- net)
SecureWorks, Inc.

Don't worry about the world coming to an end today.
It's already tomorrow in Australia.
-- Charles M. Schulz

Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.
For details and online registration, visit

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Re: GNATS documentation evaluation: From: Jim_McAward

Previous by Author: Re: GNATS documentation evaluation
Next by Author: "They don't need no stinkin' documentation..."
Previous by Thread: Re: GNATS documentation evaluation
Next by Thread: Now I really am the Doctator

What this post helpful? Share it with friends and colleagues:

Sponsored Ads