RE: Style conventions: pipelines vs. arrows, single step style vs . se ntence? (take II)

Subject: RE: Style conventions: pipelines vs. arrows, single step style vs . se ntence? (take II)
From: KMcLauchlan -at- chrysalis-its -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 12 Aug 2002 13:40:10 -0400

On Monday, August 12, 2002 1:00 PM,
Hart, Geoff [mailto:Geoff-H -at- MTL -dot- FERIC -dot- CA] was heard to proclaim:

> Any subsection that's been boiled down to a single step should almost
> certainly be included as the final step of the previous
> subsection or the
> first step of the next subsection. Single-step procedures are
> often a sign
> that you've subdivided your instructions beyond the point of
> helpfulness

> If the goal is to facilitate skimming, a simple solution
> would be to create
> an icon that sits in the margin beside the first step of any
> procedure, no
> matter how many steps that procedure has. An appropriate icon
> might be a
> simple sketch of a page with the tiny text 1--- and 2--- on
> it (the ---
> indicating Greeked text, the numbers indicating a numerical
> sequence and
> thus the start of a procedure).
> Another approach would be to make all single-step
> instructions into tables:
> column 1 says "to achieve this result" (e.g., open the file)
> and column 2
> says "do that" (e.g., press Control-O).

Well, I was thinking of some sort of icon, or even a small
box (or sketch of a page...) with the words "Do this..." :-)

In many cases, my instructions are not standalone,
in which you decide you want a certain result and so
choose this particular instruction. Instead, they
are part of a sequence in which you darn well better
do this... and have done the previous... before you
get to the next section. They may be instructions
that *can*, indeed, be executed separately in ongoing
operation or maintenance, but that *must* be
executed in proper sequence for initial setup.

Also, one reason that I have a few single-instruction
subsections is that I presage the key events that
must occur in the setup/commissioning procedure (as
a bulleted list, as a matter of fact), and then I
repeat the bullet points as the sub-headings
throughout the full-blown, detailed instructions.

I *could* make one instruction into several by talking
baby-talk, whose purpose would be purely to make four
steps out of one... in fact, I might even do that
when talking to Windows users, but in the next
section/chapter where I give the same instructions
to Linux or Solaris users... I don't bother to tell
them how to use their OS interface as part of my
product-specific instruction.

"Right-Click on the name of the certificate file.
In the resulting pop-up menu, select 'Copy".
Select the ...." Oy...


"Copy the certificate file to the working directory."

Another reason that I have some single-instruction
subsections is that the section headings correspond
to standard types of actions that the educated user
is expecting, and the instruction simply says how to
accomplish that with our product. Or, we may have
improved our interface since the last version such
that what once took five discreet steps now takes one.

Thanks for the suggestions. I'm processing.
(Whirrrrr click kaTHUNK! gri-i-i-i-ind Sproi-oing!)


Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L.

Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!

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 for more resources and info.

Previous by Author: RE: Style conventions: Pipelines vs. Arrows, Single step style vs . Sentence.
Next by Author: RE: Value of / requirement for user testing
Previous by Thread: Re: I'm taking my marbles and going home...
Next by Thread: Problems w/ Distiller 5.0 Settings

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

Sponsored Ads