TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: There's more to it than grammar From:Julie Bruce <jbruce -at- CYBERLOG -dot- NET> Date:Mon, 15 Mar 1999 16:51:22 -0600
When I write, I try to reach both audiences. As each option is introduced,
I explain the rational for that option and give instructions that a pro
would follow without any problems. I give details about why the option is
available, examples for how it may be used to enhance what they are doing,
and other information that I feel may help them to find other uses for the
option. Then, I provide a single screen capture of the initial screen.
This screen capture is desinged to give those that are not so much of a pro
a warm fuzzy feeling that they are indeed in the right location. After
that I provide a table with a series of prompts that they will see
displayed to the screen along with their appropriate responses and I might
include any additional key information that may be helpful (is this
information required or not). A pro can simply skip this information and
move on to the next section much like one can skip over a chapter summary
if they feel that they have all the information figured out for themselves.
For Windows applications, the title for the first column is Field and the
title for the second column is Description. The information in the second
column provides a description of the type of text that the software is
looking for in that field (Is it alpha or numeric or both. How many
digits is it? Where do you get the information to put in here? What other
fields does the information in this field affect? and so forth).
I feel that you really can't discount either audience but you can make it
easy for each of them to skip the parts that they are not interested in and
get right to the part that they need.
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_
