RE: "Bug" reporting for documentation?

Subject: RE: "Bug" reporting for documentation?
From: "Dawson McKnight" <dawson_mcknight -at- hotmail -dot- com>
To: caroline -at- exchange -dot- microsoft -dot- com, techwr-l -at- lists -dot- raycomm -dot- com
Date: Thu, 13 Jul 2000 18:10:15 EDT

"Caroline Briggs" <caroline -at- exchange -dot- microsoft -dot- com> writes:

If you're not confident that your docs should attract such scrutiny, then your process probably has some holes in it.

Hey now, don't prejudge my precious process, Caroline. Ours is sound enough, but I'm open to evolution. That's why I posted my question. But you already apologized, so I digress...

Sorry to sound harsh, but tons of folks on this
list would kill for the same attention to detail from the product
development teams, and I think that this is a GOOD thing.

You have a point, Caroline, in saying that cooperative development teams and some level of bug reporting are good things.

But I realize now, based on a few of the posts I've seen, that I should clarify what I mean by "bugs." I'm not talking about procedural mistakes that misrepresent the user interface, for example, and are noted by tech support during trouble calls. Those may be appropriately handled by bug-reporting software. But when it comes to line-by-line comments on draft text (e.g., "Clarify this," "Elaborate on that," "Are you sure you want to use that word?"), using bug reporting would be an unnecessary burden.

I receive hundreds of comments on the drafts I write (a blessing, I know), some trivial, some substantive. I couldn't imagine having to go back and forth to StarTeam every time I needed to read one of them, let alone asking reviewers to write elaborate instructions on getting to the right page and sentence of my doc and replacing x with y.

Is it possible that the difference lies in working on new documentation vs. maintaining existing documentation? It sounds like a few of the bug-reporting advocates are using bug reporting for doc maintenance tasks rather than refining fresh prose. Right now, I'm working on draft docs that have never been read before. Perhaps bug-reporting would work better after the document is finalized and in the field (?).

In sum, I'm not convinced that bug reporting is good for EVERY substantive error or suggestion. At least we can agree on that, right?
Get Your Private, Free E-mail from MSN Hotmail at

Previous by Author: "Bug" reporting for documentation?
Next by Author: Re: Bug tracking systems as information repositories
Previous by Thread: RE: "Bug" reporting for documentation?
Next by Thread: RE: "Bug" reporting for documentation?

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

Sponsored Ads