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.
Lulu TW wonders: <<I'm writing an Admin Guide, and one section is wholly
taken up with creating an object. Now, to create this object, you just open
a tool, select the object, and the object creation dialog box appears. In
this dialog box, there's 13 different property fields to be set...but,
explaining each property involves major discussion of what it is, what it
does, how to manage it etc (going up to five or six pages worth of
description in some cases).>>
The first part of the solution is to present the information in a sequence
that approximates how the user will approach the dialog box. If there are
any prerequisites before they click the object, cover those first. Then, one
field at a time and in a logical order, describe each field in sequence. If
there are dependencies (you can't do B until A is complete), the steps must
appear in an order that resolves the dependencies. If there are several
possible orders, with no particular reason to prefer one over another, pick
the one that seems most effective: typically, this order proceeds from the
top left of the dialog box to the bottom right (i.e., the order of reading a
page in English).
The second part of the solution is to understand the users: If some will
already know the details and just want the steps, you should structure your
information so the instruction ("do this") stands out from the details ("if
you've never done this before, here's what you need to know before you go to
the next step"). If the details are important (for example, there are five
options), include those along with the step. For example: "You have five
options: Choose [option 1] if [conditions]. Here's how this affects the
other settings on this screen. [details]"
<<I'm wondering whether to describe and explain each property separetly
first before explaining the object creation procedure>>
Sometimes that provides a useful or essential overview of the process. I
find this kind of overview very effective: "Here's what you'll be doing and
what you need to know and what you need to have available before you start.
Got everything? Okay, now here's what you do with that information and those
tools. [The procedure]"
<<Basically, to create an object, you need to create all this other stuff as
well. I've pulled the description of 'creating other stuff' into a separate
chapter that is 25 pages long. The chapter on 'creating an object' is only
10 pages...and a lot of it is taken up with xrefs to the previous chapter.>>
Personally, I hate cross-references to essential material that takes me away
from completing the current step. I end up with multiple fingers or scraps
of paper holding the manual open, trying to remember my current position
within the overall procedure while trying to find the cross-references. If
the information is essential to completion of a step, don't send me on a
wild goose chase looking for information on how to complete that step: give
me the information now and spare my poor fingers. <g> If the information is
useful but I can keep working without it, a cross-reference is a tolerable
evil.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
(try ghart -at- videotron -dot- ca if you get no response)
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell
HAVE YOU SEEN THE LATEST FRAMEMAKER PUBLISHING TOOL?
RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for
competitive pricing or view a live demo at: http://www.ehelp.com/techwr-l3
---
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.
