RE: "Bug" reporting for documentation? [long]

Subject: RE: "Bug" reporting for documentation? [long]
From: Paul Hanson <PHanson -at- Quintrex -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 13 Jul 2000 16:34:33 -0500

> Should source code management tools be used to report "bugs" in
> documentation?
We don't use a versioning control software. When there is a change to be
made to the documentation, a regular problem report is written up with
the requested change. I request that they include a print of what they
want changed so I can put both the original problem in a folder. Our
problem report system is set up that everyone that touches the problem
report adds comments.

For example, on my desk is problem report 999-2836:

Original report:
"The End User Documentation sent out to the clients needs to have 2
corrections made. These corrections are for the restart option and how
it works with flow control. See attached examples."
My Team Lead comments:
Assigned to Paul to update documentation with the changes.
My comments:
Made changes to the RoboHELP demomaster project CYCLECL, not to
v:\instruct\client\etc. This is because I made several editorial changes
to the demomaster project that I don't want to have to recreate in the
v:\instruct\etc. document."
back to Karen to close report.
Karen wrote:
This has been completed. Closing call report.
And that's how we do it.

If anyone wants the specifics on why the project CYCLECL was updated,
not v:\instruct\client\etc. was updated, email me off-list. In summary,
I'm working on a project where I've copied all the existing
v:\instruct\client documents and created .hlp files for a demonstration
of where the company is going with .hlp files.

> Should source code management tools be used to report "bugs" in
> documentation?
> 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.
If someone wants changes made to the document, they have to give
me a print out of what changes they want. I learned the hard way that if
you distribute the .doc, people make changes that make your
documentation standards . . . obsolete. For example, the last person
that got a hold of one of my .doc files bolded and underlined the "Type
Y" and "Type N" in the following 2 example sentences, and every other
place where an instruction like this existed. EXAMPLE:
<bold><underline>Type Y <bold><underline>to print the file immediately.
<bold><underline>Type N<bold><underline> to hold the print job.

My standard, by the way, is to bold the value (Y or N), not the
word Type. That's the way the Word doc was given to him.


Previous by Author: RE: Dynamic Data Leasing System Software - Need help
Next by Author: Terminology Q: Clicking on a tab displays a ?
Previous by Thread: "Bug" reporting for documentation?
Next by Thread: More salary stats

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

Sponsored Ads