Re: There's more to it than grammar

[Eric Ray <ejray -at- RAYCOMM -dot- COM>]

At 03:32 PM 3/14/99 -0500, Johndan Johnson-Eilola wrote:
>One of the more problematic assumptions about technical communication is
>that it frequently assumes users already know, in general, what they want
>to do only only need assistance in error recovery, impasses, etc. Although
>there's nearly always an aspect of this involved in technology use, we
>often forget that users usually could also use a lot of help figuring out
>what The Big Picture actually is.

You know, I wonder how much we as technical communicators
ignore the real issues of big pictures, why-to, and user orientation
(and training, Mike Wing's points notwithstanding). I mean,
really, for most reasonably literate computer users, there's far
less need for the menu-item by menu-item, click by click instructions,
and far more need for orientation and "what you're doing here"
instructions. Sure, there are times that users need "click File,
then Open", but it's safe for many audiences (particularly more
sophisticated ones) to assume that they can open a file on their
own, even if you do have to tell them where to look for it.

It's awfully easy, as a tech writer, to hide behind the shelter of
providing "complete, accurate, thorough and detailed" instructions,
while overlooking the fact that instructions meeting those criteria
can be perfectly useless to everyone using them.

For example, some sys admin instructions I've been using
(for installing and configuring software) go through a long
and tedious step by step process (the kind that Geoff Hart
named, with if Blah, then go to step 25, if Bloh, go to step
32, otherwise, continue here) to lead the reader through a process
that works. However, I can't help but to wonder if the readers
would be better served by providing  a higher-level set of
instructions (if your environment looks like this, you'll do
A, B, D, while if you have this, do A, C, B, D) and start
them on each process, but leave the "enter 1 at the prompt"
and similar instructions to the reader--assuming the
reader can read, it should work and restating the information
on the screen provides no added value to the reader.

I have a couple of reasons for thinking this...first, my attention
span doesn't carry on for reading step by step instructions when
I just need the higher-level process. If I know exactly where I'm
going, the docs are just a status-check (and if it's the skip
to step 247 kind, not even a good status-check). Second, it
would make our lives as tech writers far easier, by allowing us to
concentrate on the _information_ for the readers and getting
away from providing _data_ (that's visible on the screen anyway).
If we're not trying to itemize each keystroke the reader makes,
we're not going to spend as much time revising for programmatic
changes.

So, everyone wins. In my world-view, anyway. (Yes, the sky
is blue over here.)

(There's probably a connection between my approach to this, and
the fact that I want directions to new places in terms of
"You're going to the corner of ASD and JKL. Start on I15,
then exit and go west at 12345 South, then look for ASD in
about two miles. Go south, and your destination is on the right
in three more miles." The "go two blocks and turn left" instructions
are invariably screwed up by construction or traffic that precludes
turning at the correct place, and without the big picture,
there's no recovery information.)

Eric


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Eric J. Ray    RayComm, Inc.
http://www.raycomm.com/      ejray -at- raycomm -dot- com

*Award-winning author of several popular computer books
*Syndicated columnist: Rays on Computing
*Technology Department Editor, _Technical Communication_

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=