Quick reference material in user guide?

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

Jim Hager is <<...working on a user guide for a complex application for the
medical industry. It involves lots of screens with lots of fields and some
complex tasks for the user. I'm contemplating adding some quick reference
material inside the user guide. These blocks of material would be like a
quick summary of the tasks that are rather compex. These would interspersed
throughout a chapter as need and would be in adition to the chapter
summaries. >>

I use this technique frequently, and it seems to work well; I know that _I_
appreciate it when I find it in other people's documentation. The rationale
is as follows: the quick reference provides an overview of the larger task,
and provides mental "hooks" on which to hang the steps that follow.
Understanding where you're going and why is important for many users.
Moreover, for advanced users who merely need a refresher, the overview
material may be all that they need to read.

Most recently, I used this approach for a moderately complex
hardware/software installation guide. I have a preplanning section ("make
sure you do the following prep work before you start"), a summary of the
installation ("these are the the main steps you'll do over the next 3
days"), and finally the actual detailed installation. I even provided a
photocopiable checklist for the main steps. The SMEs loved it.

<<If so, can you provide any guidance?>>

Formatting is important. Not the "pick the right font" kind of thing, but
rather the use of chunking and white space to make the overview stand out
from the details that follow or that surround it. Cross-references are also
important; each step in the overview should direct the reader to the
detailed explanations that follow. In online help, I've been tempted to make
these links open in a secondary window so that the overall process remains
visible in the background, but my fears that a proliferation of windows
annoys too many users have made me take an alternative approach; instead, I
include a statement such as "Complete each step in the sequence in the
indicated order [link to details], then click the Back button to return to
this page and continue the overall sequence." In short, the non-programmer's
way to create a wizard!

<<Note. I'm not asking about separate quick reference guides, I'm asking
about imbedding some quick reference material inside the user guide.>>

I think those who replied in the negative probably missed this part of your
message, or at least didn't consider it as important as I did.

--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
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Enhance, optimize and automate your FrameMaker-to-PDF workflow with TimeSavers:
Define all PDF features in your source FrameMaker files ONCE, distill MANY.
Bookmark Controller, Link Controller, UnBloat & more : http://www.microtype.com

Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! 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.