RE: Features of a well-written procedure

["Geoff Lane" <geoff -at- gjctech -dot- co -dot- uk>]

Tom Murrel wrote:
[snip]
>
> Sorry, but it seems to me that 7 +/- 2 is a design tool, not a
> documentation tool. To me, a step is a discreet action that produces a
> discreet result. If I combine them, I'm simply increased the
> complexity
> rather than simplifying things for the reader/user/doer.
---

If you're documenting a procedure that you do not expect you're readership
to learn, use a flat structure with as many discrete steps as you need.
However, most readers expect a manual, user guide, or tutorial to instruct.
After an initial learning period, most readers expect to be able to carry
out the procedure without reference to the publication.

While Miller never meant to apply the rule of 7+/-2 to technical writing,
that rule is relevant to how we learn. Going back to basics, we learn how to
form individual letters and how they sound. At this stage, we write "cat" by
painstakingly forming each letter -- we say "sea ay tee, cat". Soon, we

recode this procedure to automatically form words, not letters. At this
stage we write (and say) "cat" without even thinking about individual
letters.

IMHO, part of our job is to help the reader understand what they must do. If
we write a procedure using a flat structure with twenty, thirty, or more
discrete steps, our readers have a hard time understanding that procedure.
However, by outlining, we can group the steps into logical chunks and
provide a name for each chunk. That name is a handle onto which the reader
can grasp.

IMHO, an outline (or hierarchy) is the best structure with which to present
complex procedures. For example:

Step 1 - Initialize the Xyzzy
	1. Blah blah blah
	2. Blah blah blah
	...
Step 2 - Assemble the Xyzzy to the Keefly Trunion
	1. Blah blah blah
	...

This aids the reader in the process of recoding the minor steps into major
steps. Just as we learn to write "cat" instead of "c-a-t", the steps to
accomplish each major step merge to become the step itself. Instead of
learning a sequence of twenty, thirty, or more steps, the reader must learn
a smaller number at a time. In consequence, they learn the whole more
quickly.

Just my two eurocents,

Geoff Lane
Cornwall, UK
geoff -at- gjctech -dot- co -dot- uk


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Take XML and Tech Writing courses online!  Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off!  http://www.online-learning.com/index.html.
---
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.