Tech documentation info to developers and QA?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Pooja Malhotra is <<... facing some problems when dealing with developers
and QA team>>

This is pretty much the situation everywhere in the universe. If they
discover intelligent life on Mars, and those life-forms aren't intelligent
enough to have abandoned programming in favor of something superior, the
little green Martian technical writers will write to us to complain abou the
same problem. <g>

<<Every time, I have to explain the documentation process to them and still
is ignored.>>

The usual source of such problems is that they have tight deadlines, and
don't know anything about you more than your name. Thus, when you come to
them, you're asking them to increase their workload, yet they don't have any
reason to want to do you a favor. The solution is a long-term one: even on
Mars, the little green men (not little green women... they're from Venus
<g>) are much happier helping friends and working with people who can make
their lives easier. If you can figure out how to become their friend, or how
to make their lives easier, you can gradually (it takes time) persuade them
to listen to your suggestions.

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

This too is common. The problem arises when nobody in your management team
cares about whether the product is usable. As soon as customers start
complaining, and stop buying the product, managers suddenly understand the
value of usability. Without that kind of incentive, and without management
support, you will never be able to change the interface... unless you can
prove to the developers that you can help them do their job faster. Since
they can whip together a user interface in about 5 minutes, but may take
weeks or months to write the complex code the user interface invokes to
perform its functions, you can see why they don't want to waste time on the
interface.

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

This is also a common belief, and in fact, it's largely correct. In the
ideal situation, we should always produce documentation that is 100%
perfect. Unfortunately, we live in the real world, and nobody is
perfect--particularly when we're working with less than perfect resources.
Ask your programmers this: "Programming is your department. Does this mean
you always produce perfect code with no bugs?" They'll get the point.

Where you have an opportunity to gain their gratitude and respect is when
they keep changing the user interface. Each time they do this, it wastes
their time. If you can show them how to produce fewer versions of the
interface, you can save them time. They'll appreciate that, and once they
start working with you and seeing benefits from doing so, you can start
asking for greater changes.

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

There's really only one fundamental in QA: read every line of the
documentation and follow its instructions to the letter. Don't guess what it
means, just do what it says. If they get the expected results, the
documentation is fine. If not, the documentation needs to be fixed. Of
course, you should also be doing this before you submit your documentation
for review, but a second set of eyes is important.

If the developers won't review what you write, stop asking them to--at least
for now. Use the QA team instead. Over time, as the programmers learn to
trust and like you, you'll be able to ask them specific questions about your
documentation rather than asking them to review the whole thing. Until then,
use the QA team for your main documentation reviews.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 

"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 http://www.ehelp.com/techwr-l

   Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
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
http://www.raycomm.com/techwhirl/ for more resources and info.