Re: Software Bug Databases

Subject: Re: Software Bug Databases
From: Karen Mulholland <kemulholland -at- yahoo -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 6 Dec 2007 09:23:49 -0800 (PST)

(Responding to digest - forgive me if others have made
these points)

I have to agree with Jim Shaeffer - developers and
engineers really don't have the knowledge to determine
the documentation impact of a bug. To assess the
impact, you need to know these things:
- What did we say about this before?
- What will customers see?
- How are we addressing this?

You, the information specialist, can answer the first
The person reporting the bug MAY be able to answer the
second question - but you may need to observe the
issue to understand how a customer experiences it.
Product management may define how the issue needs to
be addressed; ultimately the developer who fixes it
will have the most detailed information. Again, you
may need to observe the fix to understand how, where,
and even whether to describe it.

As a lone writer in a small company, I've found it
helpful to befriend the development team and remind
them from time to time that I need to know about any
change that customers will be able to perceive. It's
also been helpful to set up a documentation category
in the bug tracking system - this shows my development
team that I understand how to use it, and that I'm
willing to play by their rules.
It doesn't hurt that in a year, there have only been
24 issues logged against the documentation, and the
only high-priority issue among them was advance notice
of a known issue to be documented - not a correction.

You can use the bug database as one of your process
tools. (Yes, you need processes even if you are a
one-person department. :-) If you dump the bug list
for a given product version into a spreadsheet, you
can add information that you need - such as
explanations, documentation impact (if any), and names
of subject-matter experts - and you can shade rows as
you document the issues, so you know which ones you
still need to research and document.

We are uniquely qualified to determine what subset of
the information in a bug database is relevant to our
customers' experience, and to translate the geek-speak
of bug descriptions into our customers' language.
This is what we get paid for, and it's how we disprove
the notion that "anybody can write documentation" - by
demonstrating that we are *technical* *communicators*.

Karen Mulholland

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: Job market and career
Next by Author: Re: Listing publications on a CV?
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