RE: More on Validating documentation

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

Eric,

It tends to be a YMMV situation.  However, I think that a lot depends on:

1)What kind of writers have been in the picture in the past, if any.  I had
to do some re-education where I am now, because writing user docs had been
part of BA's jobs before, and "writers" were relegated to the role of
document formatting and proofreading.

2) Corporate culture:  it's harder if the corporate culture praises and
rewards engineers over other personnel (think we have it bad? Trying being
finance or admin in a software company), but it can be done.  You just have
to be more assertive about it, and prove yourself pretty consistently.  A
sense of humor is essential.

3) Your personality:  I've always been a "do what it takes to get the job
done" person, and when the opportunity arises, I assist in QA, developing
specs and designing UI.  Gives me a unique place here, because I cover a lot
of functions.  I'm the SME when it comes to user support, and have earned
the position through providing the right type of documentation at the right
time, and on time. Plus being willing to go beyond writing.  And it can't
hurt that I've found more than one show-stopping bug before major releases,
completely unrelated to documentation tasks, because I take the time to
learn the system. If you think you're just the writer, and they should be
coming to you, then it's a self-fulfilling, and damning prophecy.

I think the problems can be exacerbated if you hold to a "I'm the writer"
ivory-tower mentality, or if you don't like to speak out.  I'm a team
member, made it clear in the interviews, asked to be invited to status
meetings as soon as I arrived, offered to help in QA and production, and now
have my milestones listed on the project plans.  But I did have to ask a few
times.  Now I don't. I take the blame when I goof, and I try to come up with
a positive resolution that allows every party to save face when it's not
really my goof.

Contribute to the whole team, get outside your comfort zone and you'll find
that the prejudice goes away in a big hurry. And you get to learn lots of
cool stuff you wouldn't otherwise.

I found the same kind of prejudice against professional communicators to be
even stronger in PR, and marketing.  There was always an assumption that I
was the dumb writer chick, and that the marketing department was even more
clueless than those technical writers!  Often they were right, but just as
often they weren't. Good think I moved to tech comm, the air's better up
here :)

Connie "SME" Giordano
Senior Technical Writer
Advisor Technology Services
A Fidelity Investments Company
704-330-2069 (w)
704-330-2350 (f)
704-957-8450 (c)
connie -dot- giordano -at- fmr -dot- com <mailto:connie -dot- giordano -at- fmr -dot- com> 
 
"I am always doing that which I can not do, in order that I may learn how to
do it." - Pablo Picasso 



-----Original Message-----
From: Eric J. Ray [mailto:ejray -at- raycomm -dot- com]
Sent: Monday, March 25, 2002 9:55 AM
To: TECHWR-L
Cc: Andrew Plato; etymes -at- lts -dot- com
Subject: More on Validating documentation




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?


[snip]

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.