Re: One step per action

Subject: Re: One step per action
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Sat, 17 Jun 1995 07:52:40 PDT

I wrote, as an example:

> 6. REMOVE THE HEAD by removing the eighteen socket-head cap screws...
> 7. REMOVE THE OLD GASKET by scraping it from the head and block...

Bill Burns wrote:

>You'd put the effect before the cause? I understand your point (indicating
>the result of the action), but I'd write the sentences differently.

> 6. To remove the head, unscrew the .....
> 7. To remove the old gasket, scrape it from ....

What do you mean, "put the effect before the cause?" I'm removing
the eighteen screws so I can take the head off. I don't give a damn
about the screws themselves. They aren't a causative factor; they
are a fiddling, unimportant, boring, trivial detail, instantly
forgotten once the head is off and I can proceed with my actual work.

Experienced mechanics need a checklist of the major steps. They do
not need (and will not read) lengthy discussions about exactly how
many screws are attached to the head -- they grasp such things
by a glance at the head itself.

Similarly, inexperienced mechanics need some idea of the big picture;
major steps and concepts, followed by the fiddling details and substeps.
I would no more focus on the screws than I would tell a surgeon to
make a particular incision before I told him that he was doing an
appendectomy.

You should focus on GOALS, not details. While it's fashionable to
surround the reader by a thick fog of detail, obscuring the real
steps, goals, and techniques, it's a terrible way to document things.

Get the principles across, and the details take care of themselves.
Focus only on detail, and one misstep leaves the reader totally lost.

-- Robert


Previous by Author: Re: One step per action
Next by Author: Re: FrameMaker vs. Interleaf
Previous by Thread: Re: One step per action
Next by Thread: Re: One step per action


What this post helpful? Share it with friends and colleagues:


Sponsored Ads