Instruction suggestions?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Tom Launder (welcome to the fray!) has some questions concerning
instructions:

<<Audience Analysis: Ages: 24-50, Education: High School through Graduate.
The majority have college degrees. Computer experience: Novice to
Experienced. Gender: 90% female 10% male. >>

Congratulations on actually doing an audience analysis. A few notes: "Age"
is rarely a useful parameter, since it evokes stereotypes (e.g., "can't
teach an old dog new tricks") that have few practical implications for our
work; only when you have extremes present will an age distribution give you
important information (older folks may have vision problems that require
larger text, younger folks fresh out of school may have zero industry
experience). In each case, the important factor is not age, but rather
"proportion of audience with visual impairments" and "need to explain the
industry to readers".  As for "gender", the correct word in this case (even
if it makes some flinch) is "sex"*, and that's also a useless demographic
for most audiences because the variations within the group called "women"
and within the group called "men" are generally larger than the variations
between men and women. That's true for most of what we document.
Stereotypical male-female differences such as "strength", "hair length", and
so on may be important, but it's the implications of these differences (you
must be able to lift 50 kg to do the next step; long hair can get caught in
machinery, so wear a hairnet) and not the male/female ratio that's
important.

* "Gender" refers to how people perceive and adopt sex-related "roles", and
may indeed have strong relevance (e.g., when you're writing a policies and
procedures manual for determining spousal health insurance or pension
benefits), but gender is far more complicated than what type of genitals one
possesses. Again, the important thing is the implications of gender, not
gender itself.

The moral: When you do an audience analysis, concentrate on things that
shape how you would write, not on raw demographics. Start with a demographic
such as age, and gather information related to the effects of age, not just
the range of ages.

<<This manual must explain the entire Data Management process using a
particular program.  For many, this is their first time using the program. I
have to explain things easily enough for a novice, yet not lose the interest
of the more experienced personnel.>>

This suggests that an approach based on a high-level overview for beginners
and a more focused overview for experts would be appropriate. In the former
case, you want to explain the main concepts of data management; in the
latter case, you'd explain how these concepts are specifically implemented
by your program. Ideally, someone who finishes reading the high-level
overview will obtain all the knowledge they need to let them understand the
more focused overview.

<<When I first started writing this training manual, I thought I was writing
well enough for the novice user.  I was wrong.>>

Welcome to the club! <g> The only way we get better is by interacting with
the audience for long enough to unlearn our assumptions.

<<A screenshot I incorporated to explain a procedure had an artifact at the
end of the command line that looked like a black rectangle.  It was the
flashing cursor at the end of the line, and I never gave it a second
thought.  One person could not perform the task because they could not
figure out how to type the black rectangle.  Action taken: I used a graphics
program to remove any and all extraneous marks.>>

Good solution. This harkens back to the stories about users who called tech
support when confronted by the instruction "press any key to continue"
because no key on the keyboard was labeled "Any". This is why most people
now write "press the spacebar [or whatever] to continue". Your specific
example provides a good lesson in information design that supports Tufte's
recommendations concerning minimalist graphics: the cursor doesn't provide
useful information to the viewer, and thus should be deleted. A second
lesson is that a screenshot of typed text often serves little purpose;
showing readers where on the screen to enter the text is more useful in most
cases. Closer examination of your graphics may reveal other useless
components that could be eliminated.

<<Explanations contained in "notes" that followed the step are rarely, if
ever, read.  I thought everyone knew to read through the entire step first,
including all notes, but I was wrong. Action taken: I put a paragraph in the
introduction explaining the importance of reading each step completely,
including notes, before performing the step.>>

This is also a strong indication that you should put notes _before_ the
step, not after, to ensure that they're read. Indeed, if the note represents
an important or essential warning or recommendation, you should make it part
of the step, not something external to the step (e.g., a marginal note)
that's easy to ignore.

<<1. In the <b>xterm</b> window, type the change directory command and
change to the study <b>work</b> directory.  The syntax for this is cd
/dat/client##/client name/protocol/work.  After typing in the command press
Enter. Example: <b>cd /dat/client35/methos/my25-17/work</b>

Here, there are a variety of problems. First, you're giving the impression
that typing the command and changing to the directory are two separate
steps, when in fact they're the same step. Second, you're using more words
than necessary because you're being unspecific ("the change directory
command"), and using words ("syntax") that aren't necessarily within the
audience's vocabulary. Here's a simpler rewrite: "In the xterm window, type
<b>cd</b> followed by the directory name, then press Enter to change to this
directory. For example: [example]" Note that the command is emphasized in
some manner (boldface, different font, etc.), and that you're replacing
generalities ("type the command") with specifics ("type cd"). You could
separate "Press Enter to change..." as a separate line; I don't have any
strong feeling that this improves the procedure description, but it probably
wouldn't hurt.

<<If you are still in the <b>dde</b> directory from the discrepancy report
instructions, you need to come back up one level before you can change to
the <b>work</b> directory.   In the <b>xterm</b> window type <b>cd ..</b>
and press <b>Enter</b> to come back up one level.  At this point you should
be in your /dat/client##/client name/protocol directory.  In the
<b>xterm</b> window, type <b>cd work</b> and press <b>Enter</b> to change to
the <b>work</b> directory (see figure X).>>

Again, too much information in a single step, and much of the information is
cluttered up with extraneous words. In addition, the words "if you are still
in the ... directory" and "in the xterm window" suggest that you're not sure
where the reader actually is, and that's not a good thing. Based on the
previous steps, you and the reader should both know the directory and window
they're seeing (thus, any clause that begins with "if" becomes unnecessary);
in contrast, if the reader arrives at this point from any of several other
places in the docs (thus, from a variety of directories), then you need to
tell them how to get to the work directory from anywhere. Perhaps a small
topic on changing directories should be included in the introduction?
Finally, the goal is to inform the reader that they must get to the work
directory before proceeding.

This being the case, start by explaining the required starting conditions,
then show the reader how to get there. For example: "Change to the work
directory by typing cd C:\example\work" where "work" equals the actual
directory and path names (respectively). If this specific syntax doesn't
work for your system, provide a table that lists the instructions to get to
the correct directory from the various places the reader might start from.
For example:
If you're in this directory:	Type this:
Blahblah			cd ..
				cd work
Blah				cd work

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"In seeking wisdom, the first step is silence, the second listening, the
third remembering, the fourth practicing, the fifth -- teaching
others."--Ibn Gabirol, poet and philosopher (c. 1022-1058)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.  
For details and online registration, visit http://ieeepcs.org/2001

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
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.