Re: Bug tracking systems as information repositories

Subject: Re: Bug tracking systems as information repositories
From: "Dawson McKnight" <dawson_mcknight -at- hotmail -dot- com>
To: kimber_miller -at- acs-inc -dot- com, techwr-l -at- lists -dot- raycomm -dot- com
Date: Tue, 18 Jul 2000 14:49:39 EDT

From: Kimber Miller <kimber_miller -at- acs-inc -dot- com>
How do you decide what constitutes a documentation "bug"?

I can't answer all of your questions, but here is how my group concluded the issue of determining what constitutes a documentation bug. (This is a draft policy. Other pub departments may take other approaches, and that's OK.)



Documentation CRs should not be used for comments on DRAFT documents that are to be incorporated in the upcoming release, including substantive line-by-line and paragraph-by-paragraph revisions and proofreading comments. We do not need to create CRs for most comments on draft documents because we already have several extremely efficient and accurate methods for tracking changes:
1. Word?s track changes function
2. Hardcopy markups
3. Comments delivered by e-mail
4. Comments delivered verbally in meetings and recorded in writing

(Writers should keep either hard or soft copies of all of the comments they receive in the above forms.)


Documentation CRs should be used in the following cases:
1. In draft documents, CRs should be limited to the following:
a. Comments made by the review team about errors or substantive changes that are NOT going to be repaired until the next release or that can only be addressed in the release notes.
b. CRs should also be used to notify the documentation team of changes to the user interface that will affect their documentation.
c. Recommendations for additional documents not addressed in the upcoming release?s documentation suite.
2. In documents that have been released, CRs should be limited to comments made by clients, technical support personnel, and others to be made in the next release of the document. This kind of CR falls into the category of document maintenance.


We should not try to force documentation changes into the software-bug-fixing model, because they are two entirely different beasts. I can?t ?mark-up? the user interface to show you what I want you to change or send you a recording of what went wrong during testing. But I CAN very easily mark up a document to show you where it can be improved. Therein lies the difference and the need to handle the two processes differently. CRs tend to add more value during the documentation maintenace process.


Get Your Private, Free E-mail from MSN Hotmail at

Previous by Author: RE: "Bug" reporting for documentation?
Next by Author: Re: naming conventions for images
Previous by Thread: Re: Bug tracking systems as information repositories
Next by Thread: Any more ideas on demonstrating the documentation process?

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

Sponsored Ads