RE: Need feedback

Subject: RE: Need feedback
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 31 Mar 2003 13:21:57 -0600

Hi Carol.

The software testers I know and work with are sticklers for rules, standards, and repeatable processes. They document everything: what to test, how to report discrepancies, the standards they test against, how to perform retesting, etc. They have been a great help to me in identifying user doc errors, such as "Topic Not Found" messages and obsolete information. But, as others have already mentioned, the same processes the testers use to report application deficiencies should apply to the user documentation. If there is a deficiency, the testers report it. The bug report should cite the standard or requirement where the user doc under testing is deficient. Changes are made to the item in question (your job!), then retesting identifies whether the deficiency has been resolved. It can be an objective, controlled, consistent process.

Software applications, including the user docs, are usually tested against a set of written requirements. It sounds as if your organization hasn't defined the requirements for user documentation. The good news is, you probably already adhere to a set of requirements for your help and manuals; they just haven't been formalized. For example, one basic help requirement would be something like "The user can access a window-specific help topic for every window in the software application." Another would be "Related help topics will be linked by browse sequences." User doc requirements can also address the depth of content and order of information as well as the standards you use for your documentation, such as, "The user manual will adhere to the style and format identified in Your Style Guide." Requirements have to state the obvious but that's what helps eliminate subjectivity from the testing process.

Maybe you can enlist the testing group's help in recording the user doc requirements and ironing out standards for documentation. Documented requirements should curb arbitrary changes; if a tester wants you to move text around, the tester should be able to cite a requirement or standard that identifies the reason the current location of that text is incorrect.

Best of luck.

Peruzzi, Carol" wrote, in part:
"Now, whenever they qc a new executable in our suite, they also qc the
help, which I think is a good thing. However, now they have started
changing my sentences. Not saying that the content is wrong, just
changing the order of my sentences, or the sentence structure. =20
"Additionally, they are telling ME where I should put topics in my
manuals and my on-line help. I have 26 on-line help projects and 24
manuals. It's not that easy to move a topic from one manual to another
when in the other 24 manuals we may reference the original manual in
which it appeared.
"My question is, is this normal for a qc department to do this? Writing,
to me, is highly subjective and just because you don't like the way I
phrased something, doesn't mean it is wrong."

Order RoboHelp X3 and receive a $100 mail-in rebate, plus FREE
RoboScreenCapture, WebHelp Merge Module and iMarkupSoftware, for a total
giveaway value of $473! Order here:

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Quirky Post: Similarities between being a Tech Writer & Modeling
Next by Author: RE: Requirement analysis
Previous by Thread: RE: Need feedback
Next by Thread: Need feedback?

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

Sponsored Ads