"Bug" reporting for documentation?

Subject: "Bug" reporting for documentation?
From: "Dawson McKnight" <dawson_mcknight -at- hotmail -dot- com>
To: techwr-l -at- lists -dot- raycomm -dot- com
Date: Thu, 13 Jul 2000 17:11:29 EDT

Should source code management tools be used to report "bugs" in documentation?

My company recently started using StarTeam for documentation version control. The software works well enough for that purpose, but it is being suggested, much to my chagrin, that we should use StarTeam (which in its full-blown form is really meant to manage code) to report all major "bugs" in our documentation (excluding grammar and spelling mistakes -- but substantive changes can be numerous and extensive).

Am I crazy, or is this the bad idea that it smells like to me? A few CRs for a document I can handle, but to try to post all formal content changes as "bugs" to be fixed, verified, and closed seems like overkill to me. Does anyone have any experience with this approach, not necessarily using StarTeam, but with some other source management tool, perhaps?

I'm opposed to it because it is much easier just to embed comments within the text of the document itself using Word's track changes function or the equivalent. You can't very easily track code and UI problems that way, hence the need for bug reporting for software applications.

And if we rely on StarTeam for substantive changes, imagine the CR descriptions: "On page 2, second paragraph, third sentence, replace 'Click the Monkey button' with 'Click the MONKEY button.' Capitalization should emulate the user interface." Ridiculous!

(A note to the esteemed "Susan W. Gallagher" <sgallagher -at- expersoft -dot- com>
and other StarTeam evangelists: I'm not knocking StarTeam for version control. I really do like it, actually. It's the bug reporting I can't swallow.)


Get Your Private, Free E-mail from MSN Hotmail at http://www.hotmail.com

Previous by Author: Re: naming conventions for images
Next by Author: RE: "Bug" reporting for documentation?
Previous by Thread: Document Control on the Web
Next by Thread: Re: "Bug" reporting for documentation?

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

Sponsored Ads