More on validating documentation?

Subject: More on validating documentation?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 25 Mar 2002 12:55:22 -0500

Eric Ray wondered: <<in your experience, are relationships with developers
really as non-existent or dysfunctional as some threads on
TECHWR-L would suggest? Is there really no sense of "we're all working
together to make this overall product as good as we can make it"?>>

I've been very lucky in this respect; the developers are usually quite
willing to work with me to resolve interface problems. But I've certainly
seen enough "they won't talk to me!" queries on techwr-l over the past 9
years that I'm quite convinced that a large proportion (even if the
minority) of technical writers don't have it so good. I've even had one
long-term "you don't bug me, I won't bug you" relationship with a developer
based on a serious personality conflict; we worked together with difficulty
at best, and outright hostility at worst.

But that's not to say the good stuff happened without any effort or that
it's a perfect situation; I still need to keep them aware of my existence
and the problems I face, particularly since software development is one of
our minor activities, so I'm not working with them on a daily basis. Absence
may make the heart grow fonder, but it also makes them forget who you are
and why they should care. <g>

<<If so, are _you_, as a tech writer, part of the solution, or part of the
problem, or both? Why?>>

I aim to be part of the solution; I'm not always the diplomat I try to be on
techwr-l, but on the whole, I'd rather work with the developers than fight
them, and they seem to recognize this. One thing that helped me is that I
learned enough programming way back when that I can talk to them on their
own level; I doubt I could actually do much programming these days without a
major refresher course, but at least we understand each other when we talk

Recognizing why something doesn't work has occasionally helped me see that
they didn't really understand the problem, and came up with a kludge to get
them around it. That let my propose a slightly different approach. In
particular, I try to propose a programming solution that minimizes their
future work, and that usually provides a much more persuasive argument than
"because I said so". It's also obvious that I'm interested in what they do
(I am), and that opens lots of doors.

<<In virtually every tech writing job (contract and permanent) I've had,
I've had to spend some time in "retraining" the developers and QA staff that
I worked with.>>

That seems pretty much par for the course. The problem is that if you're
going to work reliably with developers, they have to see you as a person;
ideally as a friend, but minimally as a respected colleague. That
relationship can't be imposed; it's something you have to build, and that
takes work. And when you arrive as the stranger in the shop, you have to
start from scratch.

The busier they are, the more likely they want to know why they should take
time out from meeting their deadlines to work with you. I suspect that's why
the worst problem reports always seem to come from startups (artificially
tight deadlines and high pressure) or mature companies with an entrenched
bureaucracy (wall building and also often deadline weirdness as a result of
downsizing and frantic efforts to prop up the stock).

The biggest problem is that as soon as you try to intrude into the
development team, you find yourself in the situation of "I'm better at this
design thing than you are". Even if that's not the message you're trying to
send, it's a natural message to receive. One thing that works for me is to
_discuss_ changes or lead them to a solution rather than simply presenting
the solution outright. Moreover, I try to accept some of their suggestions
rather than just fighting harder for my own. They really do seem to
appreciate that.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at

"Every man is a damned fool for at least five minutes every day. Wisdom
consists in not exceeding the limit."--Elbert Hubbard, author, editor,
printer (1856-1915)

PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at

Check out the TECHWR-L Site redesign!

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: Where to ask the dumb (and OT) grammar questions?
Next by Author: Data on who uses Help? (Take II)
Previous by Thread: Where to ask the dumb (and OT) grammar questions?
Next by Thread: Scientfically numbered documents (Gov. manuals)

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

Sponsored Ads