Fairly long: Hidden doc agendas (was RE: Slithery Words)

[Alexia Prendergast <alexiap -at- SEAGATESOFTWARE -dot- COM>]

>"Yet, there are times when we need to make more intimate contact with the
>reader. We may need to be reassuring, provocative, even argumentative to
>make our documentation work as needed. In writing, therefore, should we not
>be able to construct sentences in such a way that we control, or at least
>mitigate, the user's emotional reaction to our words?
>
>My question to spur discussion is, 'What techniques do you use to give
>your writing more precision, to elicit the reaction from the reader that you
>want to achieve?' "

Hmmm... My knee-jerk reaction was "Bah! I'm not a touchy-feely
person, especially with regard to tech docs."

Upon further reflection... I'm still not. ;) But we do
have "hidden agendas" sometimes (and I'm not referring right
now to the "hidden marketing agenda" that was more prevalent
in the 80's.)

I write for net admins and sys admins (NT and UNIX).
Sometimes DBAs, too. Not only do I have to tell them
how to do their admin magic using our products, I
have to convince them to let our products do their
admin magic for them... As in, "just start up the
service and let it maintain your system for you."
By nature, sys admins and DBAs are a suspicious, paranoid
bunch. That's their job. So, I guess the non-objective part
of my writing is to get them to "just trust me!"... ;)

I do this by:
-Giving them thorough, accurate docs. (Which means knowing the
 software, platforms, and other technology inside and out.)
-Understanding *their* concerns and addressing them in the docs.
-Being clear, concise, and authoritative, without being authoritarian
 or condescending. (And without sounding stilted and uptight.)

The additional challenge: in previous releases, for a variety
of reasons, the docs were not complete and were not accurate.
Our existing customers were *used* to inaccurate, incomplete docs --
so they didn't bother with them. They called tech support instead.
Even our internal folks didn't have confidence in the docs and were
telling our customers not to use the docs.

We addressed this problem by involving tech support -- listening to
their feedback from customers, having them make suggestions about
doc content, etc. When they started trusting the info in the docs
again, they became our biggest ally -- they started guiding customers
back to the new, improved docs. Now, our customers are starting to
trust and use the docs again, too. We could have done spectacular
documentation (I like to think we are :) -- but, by itself, it
wouldn't have been enough to reestablish broken trust. "No [person] is
an island," and all that.

So, in addition to our doc techniques, we developed trust in-house. We:
-Kept our fingers on the pulse of the other groups (tech support,
 product management, QA, development, etc.) and kept our ears open
 for feedback about customer experiences with the product and docs
 and for feedback about our internal folks' experiences with the
 product and docs.
-Listened for people's impressions about us and found
 (and fixed) problems there. People thought the doc folks weren't
 receptive to their comments. "We made comments and they never made it
 into the docs", for example. We addressed these issues. Now people
 *know* that when they make suggestions to us, we take them into
 serious consideration and discuss our disagreements.

||A side benefit: by getting people to buy-in, we avoid last-minute
||micromanagement.

And you know what? We did it without endless meetings and bureaucratic
BS--just some common sense. It's been a very gratifying experience --
one of those things that makes me really enjoy my job and the folks
with whom I work. Now, we face similar problems with our help system,
which has been undergoing gradual improvements, but needs "the
treatment". ;) I'm looking forward to it, along with the other
customer-friendly
projects we are developing as a result!

How do other folks handle their "hidden agendas"? What other doc
challenges
do you face? (Two potential huge, but useful, topics!)

A.
--
Alexia Prendergast
Senior Technical Writer
Seagate Software
mailto:alexiap -at- sems -dot- com

>

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html