Re: Tech Documentation info to Developers and QA

Subject: Re: Tech Documentation info to Developers and QA
From: Tom Murrell <trmurrell -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 14 Mar 2003 05:26:46 -0800 (PST)

--- Pooja Malhotra <pooja -dot- malhotra -at- induslogic -dot- com> wrote:
> 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.


> Did I do anything wrong by asking them to test the doc
> for its technical correctness?

I doubt you did anything really wrong. I've worked in organizations that haven't had
writers before. Management may, grudgingly sometimes, see a need for a professional
writer, but that doesn't mean the developers or QA have bought into it.

I have learned, sometimes painfully, that you need to do a low-key sales job to the
developers and QA. Developers see everything that is not code as a pain in the a**.
And there are still some developers who believe that if they document or share the
knowledge of systems, code, and functionality that they have gained, they will no
longer be indespensible. The QA people may see you as a threat if they feel you are
doing their job.

What I've learned to do is find ways to get them to let me help. You can find ways
to them with their presentations and the limited documentation they do produce. But
that takes time, because you need to build a relationship. In the mean time, learn
what you can. Get on the system, which it sounds like you have done, and do the
processes, and document them just the way they are. Do try to make things easier for
the user, but initially you will be limited to what you write. The developers are a
team, probably, and you are an outsider, unknown and untested. They don't want to
review your work, and neither do the QA people. So do the best you can.

But most of all, look for ways that you can use your skills to make their lives
easier. If you show you are willing to learn and be helpful, over time, you have a
chance, with a winning personality, to win them over. But you can explain "The
Documentation Process" daily, and that won't have much effect on them.

> 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.

Given that you've mentioned that the QA people aren't too happy to see you either,
I'd tread carefully here. Find out what their questions and concerns are about you
and your documentation. Gear your presentation to their needs in light of the fact
that they won't initially be receptive to YOU telling THEM how to do their jobs.
Talk to some of the experienced QA people in private and find out what their issues
are. Again, approach it from the standpoint that you are trying to make their jobs
easier, but remember that you can't force their cooperation. Cooperation, like
respect, can only be earned. Most of all, don't preach to them. They'll resent it
and tune you out.

Best of Luck,

Tom Murrell
mailto:trmurrell -at- yahoo -dot- com Last Updated 03/11/2003
--This Line Left Intentionally Meaningless--

Do you Yahoo!?
Yahoo! Web Hosting - establish your business 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.

Tech Documentation info to Developers and QA: From: Pooja Malhotra

Previous by Author: RE: Smarter person than me - shifted slightly
Next by Author: Maximum File Size For Word Documents
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