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.
Eric Dunn replied to my long original post: <<Geoff Hart pointed out the
issue of being 'lost in hyperspace' an issue that I would think requires
further study. How can the user be kept 'in context' when drilling around in
on-line documentation?>>
One interesting solution appears in some recent HTMLHelp systems. Though
implementation of this technology seems generally inferior to good old
WinHelp, the multi-frame approach does work quite well. The expandable table
of contents appears on the left and the text for a selected topic appears on
the right. This provides a relatively unobtrusive view of the context (where
you are in the system, what comes before this topic, what comes after)
simultaneously with the help text for the currently selected topic.
You can provide the same support in text using nested headings or running
headers and footers, but you won't see this done often because (a) readers
can find the context easily enough by flipping pages and (b) it hasn't been
a standard practice, and thus isn't common enough to have attracted a large
following. Maybe it's something we should do more often?
<<Or, in printed documentation how do you best present detailed information
yet still allow the user to quickly find procedural instructions that don't
assume they've read the whole book?>>
That's a much tougher challenge. Let's break the answer into categories
based on the main types of printed documentation readers encounter:
- In tutorials, you assume that readers work through the tutorials one at a
time in sequence, with each lesson building on the skills they developed in
previous lessons. You thereby make a false assumption, but what can you do?
You can lead a user to water, but you can't make them think. <g> Backwards
references to the previously learned material solve the problem of "I
haven't read this yet!", but to a larger degree than elsewhere, you have to
assume that the reader has learned what's necessary.
- In reference material, you assume (false assumption number 2!) that the
people are looking up only specific concepts rather than trying to learn how
to use the software; thus, each bit of reference information must be
sufficiently complete to stand alone, but have cross-references to other
topics that build on the current topic. For example, I want to know what to
do with the "Impenetrable jargon" field and turn to the reference material;
that reference topic explains to me what the field means and what possible
values can go there (e.g., by referring to a Glossary). A cross-reference
then refers me to the "Secret hidden switch" field that lets me enter
information in plain English. And so on.
- In procedural text, you must again make sure that each procedure is
complete enough that readers don't have to look elsewhere for information on
how to complete a particular step. That means you must repeat information
that might seem obvious; for example, even if you've previously explained
that the Disaster Recovery command is under the Help menu, step 1 in the
procedure must still be "Open the Help menu and select Disaster Recovery".
Related procedures would again be cross-referenced (e.g., "see also: Secret
switch for turning off Disaster Induction Module").
Some text has features of all three of these types of text, in which case
you have to mix and match these options quite liberally. That's the fun part
of the job.
--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- )
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Buy RoboHelp Deluxe starting at only $798: you'll get RoboDemo, the hot new
software demonstration tool that's taking the Help authoring world by storm,
together with RoboHelp Office. Learn more 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.
