RE: encouraging learning by experimentation?

["Mike Bradley" <mbradley -at- techpubs -dot- com>]

> I think the lesson to take away from the Hackos seminar is to present
> the right information in the right way at the right time.

Carroll entitled his first book, The Nurnberg Funnel, after a medieval
concept of a device that put exactly the right information, and no more than
that, into one's mind at exactly the right time.

Someone wrote about the experimental mindset of early microcomputer users.
One result was that our manuals were really training manuals, not
documentation. We often provided a set of sample output files, then, in the
manual, used them to walk the user through a series of exercises. In the
exercises you could include demonstrations of errors and their effects as
well as good practices.

Can't do that any more unless we sneak into the Training Dept. Still, I try
every way I can to follow the minimalist approach--not explaining the
obvious (like Edit, Add, Delete and Quit), encouraging the user to learn
from the application instead of the manual (like scaling my screenshots so
that the details are obscured and the user has to read them on the screen),
and just not blathering on ("The table below, entitiled Reasons Not to Use
Microsoft Word, explains why a technical writer should not use Microsoft
Word").

Granted, my particular audience--stock and bond traders betting millions of
dollars a day for major brokerage firms--plays into my hands by thinking
they're too smart to ever need a manual, so giving them a brief document is
absolutely necessary.


> Oh no, no, no. This is a very bad idea. As a user, I can't stand it when I
> need to do something simple, don't know how and can't find it in
> the doc. I
> know it's simple, but, man, I've got a job to do. I don't have all day to
> play around and figure it out. If I did, I wouldn't of opened the stinken'
> manual to begin with. Always spell it out. Clearly.

Well, keep in mind that we're talking about the user guide, not the
reference section. In his later writings, Carroll notes that a good
reference section is generally a necessary accompaniment to a minimalist
user guide. Things that don't need to be spelled out include concepts that
the users already know (a popup menu of types of bank accounts that lists
Savings, Checking and Safe-Deposit Box doesn't need to be explained to bank
tellers), really simple things like Add means add and how to select an item
from a menu (assuming your users aren't likely to be brand new to
computers).

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

Yeah, that's why they have simulators. I think Carroll, or maybe it was
another experimenter, made the point that support for experimentation
generally has to be built into an application, such as fault-tolerant fields
that not only recognize an erroneous entry but also respond with appropriate
corrective messages.


> How do you approach error recovery?

I can't say I've gotten very far on that, now that our manuals are only
documentation. Nothing beyond a Troubleshooting section and the occasional
tip in a procedure. Well, I suppose I did do more when I was documenting
automated chip-making equipment. The software tended to be, um, cranky, and
there were predictable errors with (sometimes) known recovery procedures, as
in "If you disconnect the two widgets during data transfer, the big red
machine will explode. Wait for the shift supervisor to stop yelling at you
and the Ready prompt to appear on the computer screen. Then reconnect the
widgets and repeat the data transfer."

So I guess one key is identifying the likely errors. Once you do that, your
corrective measures may more or less be obvious.


>   Rule 3:  Don't force 'em to think.

Ack! Potrzebie! No thinking = no learning.

>    Rule 3a:  Don't make 'em hunt for information they need *right now*.
> It's a manual, not a mystery novel.

A key principle of minimalism. The right info, and only the right info, at
the right time.

>   Rule 4:  Don't force 'em to slow down or stop before they get to where
> they want to be.

Also a key principle of minimalism. Don't force 'em to slow down by throwin'
unnecessary info at 'em.


= Mike Bradley
  Tech Pubs



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