TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
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.
From: Dawson McKnight [mailto:dawson_mcknight -at- hotmail -dot- com]
Sent: Thursday, July 13, 2000 5:11 PM
Subject: "Bug" reporting for documentation?
Should source code management tools be used to report "bugs" in
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!