Re: Tech Documentation info to Developers and QA

Subject: Re: Tech Documentation info to Developers and QA
From: "Karen E. Black" <kblack_text -at- hotmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 14 Mar 2003 07:44:13 -0500

Pooja, your manager and the QA manager (in my job, also as solo writer, they're the same person: tech writing is under QA) should be backing you up in requiring that the user documentation (which really is part of the interface) be subject to quality assurance as well as the software. The tech writer also has a role to play in the usability/design of the site. Usability is a requirement for software as well. Can you get on the reviewers' list for the functional design/software requirements specifications?

As for making changes to the GUI, if the tech writer is part of the design team, it's easier to have influence early in the project, rather than trying to get changes made after testing has begun. QA doesn't want to send the software back to development for changes at this point. If you have suggestions about design/usability, document your suggestions and send them to the QA team leader, and copy the QA manager, YOUR manager, and the development team leader.

Also, get a friendly cow-orker (different from a co-worker ;-) ) to review your approach to the development and QA people. If you come across as condescending or abrupt, or if you don't properly rationalize your changes, you may need to re-cast your suggestions more objectively.

In my company, "QA" has traditionally started after the development team has finished coding and implemented the software to the QA environment. We are currently writing policies about the responsibility of the whole IT group in maintaining QA standards, which means that the business analysts must include QA standards when they write the project charter, before requirements gathering and system design have begun. I also have to remind people (after 2 years) what my role is on the team and in the project process. It gets tiring.

Prince John might say to develop a relationship with Dev and QA people by talking to them socially; maybe ask them to join you for lunch? This might make them more open to your input than if you just talk business all the time.

Best of luck. You're doing the right things, but maybe at the wrong time and place.

Is fearr socrú dá dhonacht ná dlí dá fheabhas.
It's better to solve the problem than to improve the law.

"Pooja Malhotra" <pooja -dot- malhotra -at- induslogic -dot- com> writes:

I am the only technical writer in our organization and facing some
problems when dealing with developers and QA team. They have their
predefined ways of doing things and so do not give ear to what I say
concerning documentation. Every time, I have to explain the
documentation process to them and still is ignored. For example, the GUI
of one of the software was not User-friendly and so I asked them to make
some changes. But I was refused straight away and was asked to document
the same. Because of the unfriendliness of the labels and terms used, I
was facing problems in documenting things. After finishing, when I asked
them to review the doc, they got pretty annoyed with me. As per them,
writing is my department and I must write accurately and should not ask
them for reviews. Did I do anything wrong by asking them to test the doc
for its technical correctness?

I have been asked to give a presentation to the QA team, where in I can
explain them the fundamentals and keys tips to test a document against
the software. I have some knowledge as per my experience and exposure to
technical writing but still would appreciate if you could provide me
some more tips.

Protect your PC - get VirusScan Online


Order RoboHelp Office X3 by March 14 and receive a $100 mail-in rebate,
plus FREE WebHelp Merge Module and FREE iMarkup Software, for a
total giveaway value of $439! Order today at

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: I hate Word, Chapter--I've lost count 8^(
Next by Author: Re: Usability ROI
Previous by Thread: Re: Tech Documentation info to Developers and QA
Next by Thread: Re: Tech Documentation info to Developers and QA

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

Sponsored Ads