RE: "Bug" reporting for documentation?

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

Dawson,

It's not necessarily a bad idea, but my two experiences with it have been
less than stellar.  In one company the developers had a horrible tendency to
transfer bugs to documentation without resolving them, figuring that
problems could be fixed with the documentation.  If you can set up the
system so this cannot happen it wouldn't be an issue.

In the second scenario, SME's and ego-inflated beta clients decided to
report EACH disagreement with wording or style as a bug.  Last I heard, one
50 page manual had over 90 bugs reported by the beta client. The company
accepted this because the beta client got anything they wanted.

If you can set up your system of priority and severity differently than how
it is set up for actual program code, I think it could be a very useful
tool. I have yet to hear of a documentation bug that caused a critical
failure :).  A system should avoids paragraph-by-paragraph bug reporting.
but perhaps task-by-task or function-by-function as to clarity accuracy and
adherence to style (which could then cover all your "replace with" bugs with
a single bug for that function or task).  Who knows...it could be a way to
promote additional usability testing for both the product and the
documentation.

On the other hand, RUN from trying to force documentation error-tracking
into a code error-tracking model.  In my current position, we chose not to
do that. Instead, we allow QA and technical reviewers to use revision
tracking in MS Word, e-mail reports, or hard-copy tracking  (very few
non-writer types are comfortable with revision-tracking in Word).  Then I
keep track of the progress of resolution as I normally would in status
reports and notes.  The only bugs assigned to Documentation in our defect
tracking system (SQA Suite) are those that are known, but not going to be
repaired in the next release.  I close them as soon as I write the release
notes, or add to the help files as seems appropriate.

I don't know if the StarTeam product allows that kind of customization, if
it does, it could be worth a shot.  If it can't, then argue vehemently for
some other method of reporting problems with documentation.

MTC

Connie Giordano


-----Original Message-----
From: Dawson McKnight [mailto:dawson_mcknight -at- hotmail -dot- com]
Sent: Thursday, July 13, 2000 5:11 PM
To: TECHWR-L
Subject: "Bug" reporting for documentation?


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!

[SNIP]