Editing online help?

Subject: Editing online help?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 27 Jun 2002 09:03:51 -0400

Beth Smith wonders: <<I am writing a paper on editing online help. I would
like to get information on what special methods, procedures, or
considerations is specific to editing online help (for applications,
standalone, and webhelp, etc.) An example would be checking for links and

In addition to the usual editorial stuff about grammar and clarity, a few
things that are either unique to online information or that take on unusual
importance in this context:

- contextual: The right topic must come up when someone hits the help
button, and the information provided must be appropriate for that context.

- correctness: The information must accurately reflect an interface that may
have changed since the original help information was created. Another aspect
of correctness might be that the correct medium is used. For example,
graphics rather then text when that's appropriate; never say "the odd-shaped
button with an icon that resembles a squashed bug or octopus" when you can
insert the graphic [*].

- completeness: No topics must be missing, and no topic should be present
for a feature that has been removed from the software.

- consistency: References to elements (menu choices, buttons, etc.) must be
done the same way throughout

- conciseness: Nobody reads help files for pleasure. If they're reading it,
they're frustrated, angry, under deadline pressure, etc. So get to the point
fast, and tell them only what they need to know.

- chunking: Ensure related information is grouped together, and that white
space is used to separate unrelated information. Use bulleted lists, tables,
and numbered lists where appropriate

- hierarchy: The hierarchy of headings must be crystal clear, and must be as
simple as possible. Unlike in print, it's difficult to grasp the entire
hierarchy at a glance, and that's particularly true for complex hierarchies.
Editors tend to be good at simplifying a hierarchy, and readers appreciate

- cross-references: No one topic covers it all, so make sure each topic
links to "more information" or "related information" topics.

- indexed: Search software isn't particularly useful yet, so make sure your
index rocks.

- browse sequence: Outside instructional design exercises, nobody ever reads
help files linearly to learn the software. Thus, a browse sequence isn't as
useful as you might think. However, the importance of sequence lies in
helping users know where they are in the help system. Consider using a tool
such as "breadcrumbs" to show the path users took to reach a particular
topic; unlike the "history" feature of a browser, breadcrumbs display the
literal path. For example: Help-->Printing->Choosing a driver.

--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
"Writing, in a way, is listening to the others' language and reading with
the others' eyes."--Trinh T. Minh-Ha, "Woman native other"

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.
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to 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.

Previous by Author: Recent and relevant: readability, usability testing
Next by Author: Quark vs. FrameMaker ... today?
Previous by Thread: Re: real tech writers? RE: Out-of-Work Tech Writers and Switching -- Careers
Next by Thread: RE: Inventive Documentation [was Re: Let's hear it for Connie...( or, go and do likewise...)]

What this post helpful? Share it with friends and colleagues:

Sponsored Ads