TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Style conventions: pipelines vs. arrows, single step style vs. se ntence? (take II)
Subject:Style conventions: pipelines vs. arrows, single step style vs. se ntence? (take II) From:"Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Mon, 12 Aug 2002 12:59:57 -0400
Kevin McLauchlan continued the discussion: <<any instruction step should
have some indicator of its status... something to make it stand out from
expository stuff as a "Do this" instruction... step numbers make it obvious
that these are "stuff you should do,
now". [Miscellaneous folk] keep demanding that I break procedures down into
smaller and smaller sections... However, the profusion of sub-sections means
that inevitably some sub-headings will have just a single step.>>
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
(i.e., the "granularity" is way too fine). I'll concede that there might
theoretically be cases where the single step requires its own section, but
I'd have to see a concrete example to confirm this.
<<So, now I'm trying to decide on a visual cue that could be used both with
numbered multiple steps, and with single-step items to indicate that, yes
these are operations that you must perform.>>
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). This suggestion is similar to what
the information mapping folks advocate, but using tables isn't something
they've patented thus far, so feel free to modify the approach and call it
your own. <g>
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The skill of writing is to create a context in which other people can
think."--Edwin Schlossberg, designer (1945- )
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
