Re: Software Bug Databases

Subject: Re: Software Bug Databases
From: <neilson -at- windstream -dot- net>
To: <baj357 -at- gmail -dot- com>,<techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 5 Dec 2007 19:40:06 -0500

Yes, you are asking for too much. You need to step back and think about what constitutes a bug. In particular, if the documentation says X, but the software does Y, the bug often cannot be attributed to one or the other without careful thought. Sometimes the discovery of the bug leads to the understanding that neither X nor Y was correct, and that both doc and software will need changing. In that case, it's likely best to split the bug into two parts, one assigned to a software developer, the other to a tech writer.

If you do not categorize bugs irrevocably, then the category, assignment, description and disposition of the bug can be modified as understanding of it increases. Sometimes a bug is solved by a method that we often joke about: Document it!

It should be possible for the team members, including software, hardware and management, to generate, to comment on, to reassign, to close and to re-open bugs as needed. There is nothing wrong if the comments for a bug go like this:
--Reassigning to Tina. This is a Doc bug. -Dil
--Reassigning to Dilbert. Description matches what the spec requires. -Tina
--Reassigning to PhB, and opening a bug on the spec, which is wrong. -Dil
--Meeting agrees with Dilbert. Spec changed. Reassigning to Tina. -PhB
--Fixed doc to match revised spec. Closed. -Tina

There are several bug-management systems available, and some are free. Where I currently work the JIRA (as in Go-jira, that is, Godzilla) commercial system from Atlassian is in use. Bugzilla is another, and I believe it is free.

--Peter Neilson

> I'm hoping to gain some insight to hopefully my common issue as a tech writer for software. At my company, the software bug database is also used to submit related doc bugs. The submitted information about the bug is mainly related to the software and, as a result, requires quite a bit of investigation to find the doc impact--if any. The bug basically states doc impact, doc deliverable, and related product. Currently, writers read the software bug and investigate the suggested doc impact. A submitter can suggest a doc impact even if they are just guessing at it. And it's up to the writers to figure it out.
> Have any of you found a more efficient process? So far, suggested doc-specific fields in the bug submission form have fallen on deaf ears. And I don't expect submitters (developers, engineers, etc.) to elaborate on the doc impact, at least not within the bug database. Am I asking for too much? Thanks!


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: Listing publications on a CV?
Next by Author: Re: Post current product user docs to company website?
Previous by Thread: RE: Software Bug Databases
Next by Thread: Re: Software Bug Databases

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

Sponsored Ads