Instruction Suggestions

["Launder, Tom" <tlaunder -at- synteract -dot- com>]

Hello list,

This is my first time posting a question and I would like to introduce
myself.  My name is Tom Launder and I'm a new technical writer at my
company.  Currently, I'm the only technical writer here.  This list is
wonderful and I have learned many things by reading the digests.

I would like to ask for some critique of what I have written regarding a
particular step. Before I give the section for critique, I want to give some
audience analysis.

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.  

Manual Description:

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.

Real Life (TM) Learning Examples:

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

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

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

I could go on, but I just realized that I'm writing to ask for some help!
Here is what I believe to be a convoluted explanation of a procedure.  

To give you an idea of the visual appearance, I'll use html style. For those
without html experience, I am using <b> </b> to represent "bold." 

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>

-- or --

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

Please give me helpful suggestions on how to word a step like this.  I have
ideas on how I would simplify this, but I would love to hear from the
experts here on the list.  

Take care,

Tom Launder

 

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