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.
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
Education: High School through Graduate. The majority have college degrees.
Computer experience: Novice to Experienced.
Gender: 90% female 10% male.
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
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.
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.