Encouraging learning by experimentation?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Lois Patterson reports: <<Another topic discussed at the Hackos seminar I
attended recently (which I mentioned on another thread) was encouraging
users to learn by
experimentation.>>

This is certainly a sound, time-tested pedagogical principle, and
particularly for those whose learning style involves "learning by doing".
But when it comes to documentation, advocates of this theory sometimes make
a crucial mistake: they forget that not everyone actually wants to learn how
to use a product. Instead, many readers simply want to follow a procedure
and get the job done. If you're writing instructional material and training
people, teaching by experimentation works very well. It works less well in
procedural documentation. With that caveat in mind:

<<Hackos indicated that user documentation should indicate to the user how
to recover from errors. People learn when they make errors.>>

Both are very important principles to keep in mind when writing. The design
problem then becomes how to separate out contextual information (why you're
doing what you're doing, what you need to know before you can try to do it,
and how the doing could go wrong) from procedural information (forget all
that context and just give me the steps I need to follow). That's probably
the simplest way to adopt the Hackos approach.

<<In practical terms, has anyone tried to encourage experimentation by users
in user docs?>>

We don't have the resources to write wizards, so I usually include a "do it
yourself" section in my online help that basically lists the overall steps
in a procedure, describes the goal and some characteristics of each step,
and links each step to the help topic that describes it so they can find
details, if required. The help topic then says "go ahead and build your own
system using these steps... don't worry about getting it right, just play
around and see what happens". Seems to work quite well.

<<How do you approach error recovery?>>

Me? I pull the plug on the computer, and when everything grinds to a halt
amidst clouds of blue smoke, I blame it on Microsoft. <g> A tad less
facetiously, I try to work with our interface designers to head off the most
obvious errors through careful consideration of how people are likely to
work with the user interface. This eliminates many problems right from the
start; in fact, one add-in utility for our software just got sent back to
the drawing board (in part) because I demonstrated that the metaphor was
simply unusable. In playing with software while I'm creating the
documentation, I spend considerable time getting a feel for the logic (or
sometimes the illogic) of how things work and for how I could break that
logic by departing from the path the programmers intended me to take. Once I
know these problems, I can create text that guides readers away from the
problems and down the most appropriate path. You can't ever create something
foolproof (Nature always evolves more clever fools), nor can you cover every
possiblity, but you can at least cover the most likely causes of error.

For example, we produce a datalogger that records data on heavy equipment,
and a data shuttle that lets you download the data and bring it back to the
office. One sure way to lose data and perhaps fry the electronics in the
process is to disconnect the two devices in the middle of data transfer. So
my first big statement in the procedure after "connect the two devices" is a
prominent warning about the consequences of disconnecting them before they
see the "all clear" message.

<<Obviously experimentation is not appropriate for nuclear plant workers or
some such thing.>>

Obviously you're not a fan of the Simpsons. <g>

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada 
 


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