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.
I am just reading this thread this AM (13 April 2007)
It seems that there are a number of issues that come to mind about this
exercise that you are involved in.
I have several questions.
1) Why are the doicuments being compared to the requirements, and not to
the actual opertion of the application.
2) Why weren't the peer reviews ( waltkthroughs, technical reviews, and
formal inspections) c0onducted while the product/application was being
3) Are the developers involved at any time during the writing of the
4) Why wasn't QA involved in the development of the applicatin, documents,
and requirements gathering.?
5) Is this exercise (as discussed in this thread) the 'normal way of doing
business in the company?
6) How is this effort andy different from previous efforts?
7) Where is Requirements Traceablility if this effort, or is there any?
8) How does this effort tie into the "Earned Value" of the overal company
goals in monitoriung the expenses of this, and other projects (both prior to
this project, and expected follow-on)?
9) Is it cost-effective to do this cross-checking at the tail end of the
Do any of the above questions suggest that the entire process needs to be
If there are any questions that I have not raised that should be discussed,
they might be good fodder for future discussions on this thread.
Food for thought.
----- Original Message -----
From: "Mary Arrotti" <mary_arrotti -at- yahoo -dot- com>
To: "Michelle Vina-Baltsas" <Michelle_Vina-Baltsas -at- datascope -dot- com>;
<techwr-l -at- lists -dot- techwr-l -dot- com>
Sent: Thursday, April 12, 2007 11:49 AM
Subject: Re: Validating manuals - PART II
> This sounds less like your docs are being validated against the reqs and
> more like they're being used as a testing tool to verify that the UI
> conforms to the UI requirements. And, as a result, you're being asked to
> change your docs so that QA can do this more easily. Is that correct?
> I do support collaboration with different groups & help out with QA as I
> can. But I really view this as a poor methodology - at least based on my
> This is the actual relationship as I see it: Requirements > UI > Doc.
> QA should verify that the UI conforms to the requirements and then that
> your doc conforms to the UI. To go from requirements to doc doesn't make
> sense to me (unless you're writing before there is any UI).
> It seems that with this methodology - this scenario is possible:
> Reqs say A
> UI shows B
> Doc shows A (based on Reqs)
> QA checks - UI & Doc are different
> Doc changes from A to B
> QA checks - Reqs and Doc are now different
> Doc changes from B to A
> UI changes from B to A
> To me, this would make more sense:
> Reqs say A
> UI shows B
> QA checks - Reqs & UI different
> UI changes from B to A
> QA checks - doc shows A - same as Reqs and UI
> Sorry - I can't give you any suggestions for how you can set up your docs
> in this effort. I've never worked in or heard of any organization working
> this way.
> Michelle Vina-Baltsas <Michelle_Vina-Baltsas -at- datascope -dot- com> wrote:
> Thanks to all who responded to my post. I want to clarify that QA is not
> only validating that all the functionality is documented in the manual
> based on the UI, they are also validating that the UI requirement was
> interpreted correctly by the writer (that would be me). So, if the UI says
> the XYZ button should be blue, and the Ops book says it will be green,
> that's would be an issue. However you slice it, it's a lot of extra work
> for me!
> Is there a smart way to do this? Does anyone have to do anything like this
> for their QA departments or am I the only UNLUCKY soul. Maybe I can
> suggest that they just validate that the UI document table of contents be
> captured in the Ops book rather than every single requirement.
> Thank you,
> Michelle Vina-Baltsas
> Technical Writer
> Datascope Corporation, Patient Monitoring
> michelle_vina-baltsas -at- datascope -dot- com
> Sucker-punch spam with award-winning protection.
> Try the free Yahoo! Mail Beta.
> 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.
> Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
> full Unicode support. Create help files, web-based help and PDF in up
> to 106 languages with Help & Manual: http://www.helpandmanual.com
> You are currently subscribed to TECHWR-L as hbacheler -at- aol -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
>http://www.techwr-l.com/ for more resources and info.
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
Now shipping: Help & Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help & Manual: http://www.helpandmanual.com
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-