Spell it out a second time within 4 pages, or cross-ref?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Genevieve Roberts reports: <<I have a number of dialog boxes to explain that
have the same search criteria. For example: In the Select Job dialog box,
the user can search on Active & Pending Jobs or Done Jobs... This dialog box
opens to a custom search form if the user selects the Custom radio button.
In the custom search form, the user can choose Active, Pending, Done, or
Closed jobs upon which to search. I have the same kind of repetition for
Tasks, Sessions, Samples and Images... Would you define Active Job on, say,
Select Job on page 441, and Custom Search Select Job on page 444, put a
cross-reference to only the page number 441? Or, given that it's a one-line
definition, would you consider it more convenient for the reader to have the
definition presented?>>

One possibility might be to turn the task on its head. If the reader has the
ability to create custom thingums in several places, sometimes it's
worthwhile creating a separate section of the manual entitled "Creating
custom thingums". Under this heading, you'd have a brief explanation about
the risks and rewards of customization, followed by subheadings on how to
customize specific thingums (jobs, tasks, sessions, etc.). In this way, the
text is only repeated once, and the reader learns everything they wanted to
know about customization in one place.

That approach doesn't always work. Sometimes the most logical approach to
the documentation really is to focus on (say) the "select job" dialog box
and walk through all options, including customization. Speaking as the
reader, I personally prefer not to have to flip pages to reach crucial
information. I've occasionally had to do this, with one hand on the mouse, a
scrap of paper inserted in the manual to find the original procedure, my
other hand holding the cross-referenced page open on my lap. Annoying,
awkward, and inconvenient. The advantages of repetition to the reader
outweigh the relatively minor disadvantages to the writer in my opinion.

Another thought: Have you considered thinking _inside_ the box? <g> If the
repeated material is short and must be repeated frequently, sometimes a
table approach works very well. Run the tasks (Select job, task, session,
etc.) across the top of the table, then run the label for the repeated text
(active, pending, done, etc.) down the first column. If the text describing
"Custom" works for all the tasks, insert it in a single row that spans the
entire width of the table (i.e., so that the text falls under all the
headings at once); if not, insert a cell containing the text under the first
column for which it's relevant, and add a note such as "see at left" under
any other column headings it relates to; you're still cross-referencing, but
the text is on the same page and thus repeated only once. Spread the table
across as many pages as necessary to cover all the options.

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


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at 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.