Instruction Suggestions

Subject: Instruction Suggestions
From: "Launder, Tom" <tlaunder -at- synteract -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 11 Oct 2001 11:49:51 -0700

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.


Follow-Ups:

Previous by Author: RE: Use Cases
Next by Author: Instruction Suggestions: A Rewrite
Previous by Thread: RE: RoboHELP Help
Next by Thread: Re: Instruction Suggestions


What this post helpful? Share it with friends and colleagues:


Sponsored Ads