Thinking patterns (sequential vs. other instructions)?

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

John Fleming reports that his project supervisor <<... made an interesting
comment on the way technical writers think and how we write instructions...
as a group, we are really good at writing sequential
instructions--instructions typical of tool use and where order is
important... Where we run into trouble, and one of the reasons tech writers
don't seem to survive long on this project, is that we are documenting work
flow, where order may be dictated more by best practices than by
necessity, and where the need to perform some steps my be determined by the
results of other steps.>>

I think it's a question of experience, not inherent skills. Most of what
techwhirlers document is sequential because many of the tasks our audience
perform are sequential at their bottom level, and it's natural for us to be
most skillful at doing something you do frequently. But in some ways, we're
putting on blinders when we do this, because in the real world, many tasks
are not purely sequential; there are branches, decision points, alternative
ways to accomplish something, options within any given approach, and so on.
Since we do this less often, we're less good at doing it. Moreover, this
borders on instructional design, which is another area of expertise that
many of us never study.

Where most documentation fails (in my opinion) is not in presenting the
sequential information that lies at the base of most tasks, but rather in
the failure to provide the higher-level information that helps readers
understand the various procedures that make up a task. In short, our failure
to recognize that the real world isn't necessarily linear, and that simply
presenting a series of procedures forces the reader to determine how to link
the procedures together to accomplish a task. Tutorials sometimes help, but
many tutorials are based on simply teaching users how to use the most common
procedures rather than linking these procedures into tasks. We need to
provide a high-level schema (mental model) of the possibilities, and what
features of the software tie into these possibilities. In effect, we need to
explain the metaphor for the software and provide guidance in how that
metaphor helps them accomplish a task; that is, we explain the overall
method for working with the software, then guide readers gently to the
sequential information (procedures) needed to accomplish those higher-level
tasks.

An example: You'll rarely see a word processor manual that explains various
key concepts such as the fact that users should use tabs rather than spaces
to align text (or should use paragraph indents defined directly in the
style), or that despite the fact that you see a whole white window in which
to type when you start a new document, you generally can't just click midway
down the screen and start typing. Neither do the guides explain the need for
making backup copies, where the formatting information is buried (in
WordPerfect, in the "reveal codes" window; in Word, in the paragraph
markers), which features don't currently work as designed (e.g., Word's
autonumbering), and so on. In short, we get detailed descriptions of how to
do X, but no explanation that X is an option and why we should consider
doing it.

Where we do see the schemata, it's usually in an intrusive and annoying
form: think of Clippie, Word's dreaded "I see you are trying to write a
letter can I help you or would you rather just shoot me now" help wizard.
I'd rather see this in the manual as "here's how you'd use Word to write
business letters: pick a template, modify the template for your needs,
actually start typing the text, then proofread it. To do this, you'll need
to know templates (page 117), editing (pages 32-35), typing (pages 1-30),
and proofreading tools (see grammar checkers in ch. 12 and spell checkers in
ch. 11). Okay, the order of those instructions sucks, but you get the point.

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

"I vowed [that] if I complained about things more than three times, I had to
do something about it."--Jon Shear

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to http://www.cublea.com

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