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: encouraging learning by experimentation? From:"Richard G. Combs" <richard -dot- combs -at- voyanttech -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 6 Dec 2002 15:23:52 -0700
Sean Hower wrote:
> As always, what you do will depend on:
>
> 1. What you're documenting
> 2. Your users
> 3. Their goals
> 4. Time
Bingo. If Hackos were here, she'd chant "user and task analysis, user and
task analysis" -- and encourage you to attend her seminar with that name.
:-)
If the task is linear, spell out the steps clearly, don't make the reader
figure out what to do. For instance, instructions for replacing the toner
cartridge in a printer shouldn't "encourage experimentation" about which way
to insert the cartridge -- they should state clearly how to do so.
OTOH, if the task is non-linear, especially if there are many choices/paths
that may be equally valid, encouraging the user to try various combinations
may be the best approach.
I've done this when documenting dialogs in which there are several
interdependent settings. Rather than provide lengthy tables listing all the
possible combinations (which no one would want to read), I briefly explain
the settings and how they affect each other, and then encourage the reader
to "play" with them until satisfied with the result.
This works best, of course, when the interface is designed to support
experimentation by giving the user meaningful feedback. Graphics
applications are prime examples, letting you change a filter setting, etc.,
see the effect, and undo or modify it further until you're satisfied. No
text descriptions of various Sharpen or Blur settings will ever be as useful
as just being told, "go ahead and experiment; if you don't like it, click
Undo."
Even in linear tasks, however, you'll never convince me that anyone but a
complete computer novice needs some of the "overdocumentation" that I've
seen all too often:
"To copy the frammis using the mouse (for an alternate method of copying,
see Table D-8 in Appendix D, "Keyboard Shortcuts," page 734): 1. Move the
pointer to the word Edit on the menu bar (which appears below the window
title). The word Edit becomes highlighted. 2. Click the left mouse button.
The Edit menu appears. 3. Move the pointer to the word Copy. The word Copy
becomes highlighted. 4. Click the left mouse button..."
Nuclear reactors (and such) aside, I've seen more manuals that suffer from
too much information than from too little.
My 0.02
Richard
------
Richard G. Combs
Senior Technical Writer
Voyant Technologies, Inc.
richardDOTcombs AT voyanttechDOTcom
303-223-5111
------
rgcombs AT freeDASHmarketDOTnet
303-777-0436
------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/techwr-l
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!
---
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.
