More on Validating documentation

["Eric J. Ray" <ejray -at- raycomm -dot- com>]

All,
I've been thinking about the "Validating documentation"
thread, and would like to kick out a couple of
questions and one anecdote.

I'd also (this is Eric a list member, not with the
Admin hat on) ask both Andrew and Elna _NOT_ to respond
on list to this message. I think there are some interesting
issues here, and I'd really like to see a broader discussion
of what, if any, the underlying causes are. Broad
discussions, particularly on this topic, tend to get
polarized and heated quickly, and I'd like to put that
off as long as possible.

So, 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"?

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

Ok...so the anecdote:

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.

Basically, when I started, their expectations were
that a tech writer was to sit in his/her office,
crank out docs, bug the developers with questions at
times, and little else.
My expectation was--and is--that an effective tech
writer participate in the product development process,
contribute to the _product_, contribute to the _team_,
and basically make a difference.

This retraining process has _always_ succeeded.
As far as I can tell, I've never left a position
and not had my absence noticed, nor have I (while
still in a job) observed any of the issues with
lack of respect etc. that I see discussed here.

Well, it's not been entirely easy--sometimes
it's been necessary to have one (or more)
heart-to-heart chats with developers or development
managers--but they've always come around and
accepted me as a full team member.

(The story of the retraining process and the roles
that I end up performing in the development team is long,
but I'll write it up and post it if requested. It's not
rocket science, at any rate.)

What's the result? Well, there are several, but I
think that the most telling result is a bug that was
filed against the documentation on Friday. A fairly
significant parameter can be some integer value
from one to n. The docs showed two possible
(different) max values for n (big whoops on Eric!).
Later code inspection showed that the code supported
yet another max value, and nobody actually remembers
what was tested and should therefore be documented.
One of the developers filed the bug, and, in addition
to describing the problem, he went on to add that
"the documentation was carefully reviewed, but
we all missed this."

I find that most telling--if ever there were a good time
to either let someone else shoulder the blame (deservedly,
in this case) or to just remain silent, this was it.
However, the developer deliberately made it clear
that he and others had _also_ failed to catch the goof.
(My assessment? It was my fault--I should have found it
but didn't.)

Now, I don't work in a finger-pointing environment,
and there will be no consequences (other than my
embarrassment) to this goof. However, that example
shows that it's fully a _team_ environment (all
cliched usage of that term aside) and that the
development team see that the docs are the product
of teamwork, just as the code is.

Is this really as unusual as discussions on TECHWR-L
make it seem?

Eric
ejray -at- raycomm -dot- com

(If you want to respond to this, but need to do so
anonymously, email me offline and I'll make it happen.)



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