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

[KMcLauchlan -at- chrysalis-its -dot- com]

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

 vs

"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!)

/kevin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L. 
http://www.cafepress.com/cp/store/store.aspx?storeid=techwhirl

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!
http://www.ehelp.com/techwr-l

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