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.
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.)
Regards,
Dawson
________________________________________________________________________
Get Your Private, Free E-mail from MSN Hotmail at http://www.hotmail.com