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.
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. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
