Re: Best Practices in Context-Sensitive Online Help

Subject: Re: Best Practices in Context-Sensitive Online Help
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Mon, 6 Jul 2009 10:37:15 -0700

The online help should be task-oriented rather than driven by the UI.

If a dialog is used to perform more than one task, there are several options:

- If there's an overview topic that includes cross-reference links to
all the relevant task topics, use it as the target.

- If not, link to the most common task and have cross-reference links
to the other tasks, or

- create a "landing page" for the dialog with links to all the tasks.
Such landing pages should be suppressed when generating a PDF
(assuming you're single-sourcing online help and print documentation).

Eclipse lets you define multiple targets for a context ID, and pops up
a dialog for the user to choose among them. However, I think that's a
very bad design, as there may not be enough information in the pop-up
for the user to pick the right one.

Ideally, fields in dialog boxes should be documented by explanatory
text or pop-ups right in the dialog. Don't waste the user's time and
bloat the doc by documenting self-explanatory fields.

On Mon, Jul 6, 2009 at 10:19 AM, Sue McKinney<smckinn2001 -at- yahoo -dot- com> wrote:
> All,
> I've been asked to present information on the best way to redesign our online help, currently NOT context-sensitive, to be context sensitive. In the past I've written help topics describing each dialog and linking to the associated tasks that can be performed. That way the procedures aren't cluttered with all the field explanations, and the procedural topics also link back to the associated dialog topics. Make sense?
> Or is there another way? The reason I might not just link to a procedure from each dialog is that a) there may be more than one task that can be performed from a certain dialog or b) an individual dialog may be only 1 step in a larger procedure.
> Thanks, and please respond to me directly as well as to techwr-l as I'm on digest.
> Sue McKinney

Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help
2009 tips, tricks, and best practices.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Best Practices in Context-Sensitive Online Help: From: Sue McKinney

Previous by Author: Re: job-hunt weirdness
Next by Author: Re: job-hunt weirdness
Previous by Thread: Best Practices in Context-Sensitive Online Help
Next by Thread: RE: Best Practices in Context-Sensitive Online Help

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

Sponsored Ads