If you had to teach (Take II)?

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

Lil wonders: <<I'm getting to run a workshop to train our project managers
how to write user manuals... After the workshop, for every project they
release, they will be expected to produce user guides (for two different
types of user) and data set-up/config guides.>>

Must be nice to work at a place with so much spare time that the project
managers have no project management work and must write manuals just to look
busy. <g>

<<For the user guide, I'm intending to provide some really bad instructions
for making a sandwich and sit back and laugh as they try to make this
sandwich without knowing where the bread is. We would then work from the
problems encountered in the bad instructions upto the pre-prepared (sorry
Stan!) model answer:>>

Be very wary about trying this approach. In previous discussions about
classroom exercises, many techwhirlers have expressed outrage at being given
such a trivial task. Given that my Mom has encountered a similar attitude in
a class she gave to a bunch of non-writer adults, I expect any group of
project managers would react similarly. You'll probably find it far more
effective to get them to write sample instructions based on their own
projects, then pass those to other project managers with the following
instructions: "Follow the procedure you've been given exactly and literally.
Don't interpret anything or guess at what it means. If you don't understand
it, don't try to figure it out; come to a grinding halt and announce to the
author: 'I just don't get it'."

This approach makes it very clear to the authors how intelligent, educated
people (their peers) will misunderstand something written by experts to meet
their own needs rather than the needs of users with different knowledge and
expertise. It also makes it clear that the problem isn't "idiot users"; it's
more universal than that. Getting the users of the instructions to explain
to the author exactly where they failed makes it very clear where the
problems lie, and gives a strong clue about what to do to solve those
problems.

If you must use the sandwich approach, preface it with a very clear
introduction: "I want to start you all off with a completely trivial example
to illustrate a point. Then we'll apply what we learned from this simple
example to something more complicated, namely your own writing." That robs
the example of much of its sting, gets more buy-in from the student, and may
even actually accomplish the stated effect.

<<I've written a style guide. I've also created a template for each of the
doc types, that use a toolbar that contains every formatting command they
could ever need (Want Bullets? Click the button that looks like a bullet...)
and I've written instructions for using the templates, so I was hoping to
keep the Word and word elements of the workshop to a minimum (beyond the
obvious Consistency is Good and Know thy Audience blah).>>

Don't forget to include the actual text that belongs in the template (e.g.,
all the headings, from table of contents through to index) and text prompts
that explain what goes under each heading. For example, under the "overview"
heading, try the following: "In 200 words or less, explain what this module
does, why the user should care, how it interacts with other modules, and how
they could kill themselves or their co-workers by misusing this module."
Under the heading "Procedure", you might include the following prompt:
"Replace this heading with a verb ending in -ing and a few additional words
that describe the task: for example, creating a template." Next, list the
first step in the procedure, with the following text: "Copy this step as
many times as needed. Each time, explain which menu to open or button to
click, then which option to select. Include bullets for each option and
explain when to choose each option". And so on.

See the principle? The author simply places the cursor at the start of this
text, writes an explanation of what the module does, deletes the words that
say "explain what this module does", and continues in this manner for each
of the items you've listed until they reach the end of the list. Think of it
this way: It's more important for your experts to get the right facts down,
in adequate detail, then it is to worry about formatting. Formatting is
relatively mindless work that can be done later in a few minutes; use their
time to do things that only they can do, namely writing down the details.

<<And if any of you are having a Friday early and want to try your hand at
bad instruction writing, I'd appreciate it -- it's really hard!>>

Actually, it's pretty easy to come up with really bad instructions. Just get
your project managers to write them. <g>

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at
http://www.ehelp.com/techwr
---
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.