Re: encouraging learning by experimentation?

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

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 G. Combs
Senior Technical Writer
Voyant Technologies, Inc.
richardDOTcombs AT voyanttechDOTcom
rgcombs AT freeDASHmarketDOTnet

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

Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from
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 for more resources and info.

Previous by Author: Re: The debate that won't die
Next by Author: Employment history low points
Previous by Thread: RE: encouraging learning by experimentation?
Next by Thread: Re: encouraging learning by experimentation?

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

Sponsored Ads