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.
Sure. My last three employers have used the a bug database to report errors in
the code, the test plans, and the user documentation. I prefer to have the bugs
listed and rated. It lets me know what the marketing/engineering/support people
(who determine the rating) think is very important to fix and what might be able
to wait until the next release.
It also helps me keep track of the changes to the user documentation. My only
gripe is that people put in stuff like "the dose explanation isn't detailed
enough" rather than listing specifically what they were looking for that they
didn't find. Still, I think it's a good tool.
It has solved the problem of having some writers make changes to the documents
without putting in comments. They have to respond to the bug with the final
change so the bug is closed.
Sigrid
Dawson McKnight wrote:
> 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.
--
Sigrid Schoepel
ADAC Laboratories, Geometrics
6400 Enterprise Lane, Suite 201
Madison, WI 53719
phone: 608-298-2100, x8118
fax: 608-298-2101
email: sschoepe -at- adacgeo -dot- com
I feel much better now that I've given up all hope...again.
