Re: Talking Down

[Sella Rush <SellaR -at- APPTECHSYS -dot- COM>]

While I think some people have a good point about why your manager felt
the need to dictate on this minute issue, and the possibility of a
larger issue, I have a suggestion about how to address this particular
point:

(I'm assuming that her objection was to specifying to the reader that
they need to "type" something in--that if they can't figure out that
they're supposed to type something, they shouldn't be working there.)

  I would take the position with her that documentation isn't only about
providing the basic information--it's also about making a subject easier
to learn and a task easier to execute.  It's not really about whether
they can "figure it out" but about making it as effortless as possible
to do.  It's not a matter of them not knowing what to do, it's about
them them not spending time identifying the context.

Of course we're only talking about a few seconds in each case, but as a
general philosphy it adds up--in addition to the seconds here and there
gained on every procedure, it's also about giving the user confidence in
the documentation and fostering a willingness to use it--timewise, that
means learning how to do a task right the first time instead of fiddling
around figuring it out.

Most of our techniques aim to streamline the learning and doing
process--it's why we use headings, why we work so hard on structure, why
we number instructions, and why we use clues like different fonts,
icons, symbols, and even graphics to give the reader some context.

So if this were my boss, I'd probably make a point of explaining how
that little innocent word "type" has very little to do with providing
essential information and everything to do with giving those programmers
a break--they've already got way too much on their mind <g>.

 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