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.
Sue McKinney wondered: <<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's the conventional definition of context-sensitive help: it
provides help for the current context (what you're doing), not for the
product as a whole.
That approach is much rarer than I'd like, since most help systems I
use still just dump you directly into the table of contents for the
product as a whole. That can be overwhelming, particularly to users
who are already intimidated by the product, and it can be a PITA
trying to find the correct topic from that landing page. With
_embedded_ context-sensitive help, the help can be set so that it's
available at all times (e.g., in a child window) and what you see in
that window changes as you change contexts (e.g., by opening a new
dialogue box). MadCap's Blaze (possibly other MadCap software I
haven't used) makes this resource available in addition to
conventional online help.
<<That way the procedures aren't cluttered with all the field
explanations...>>
Ideally, most fields should be self-expanatory. This is done
conventionally using "affordances", which are basically clues and
hints that help the viewer understand the meaning of a field without
having to open the help file. This is also a job for "what's this?"
help: hold your cursor over some object and the interface will tell
you what the object does (e.g., tool tips) or how to use it (e.g.,
where you click a "?" icon, the hovertext becomes far more than just
the name of an icon; it actually displays short description of how to
use it whatever you're pointing at).
The important point about "cluttered" with explanations is that if the
explanation is necessary, it isn't "clutter". The trick is to find a
way to present that information clearly while minimizing clutter.
Sometimes the clutter (e.g., field-level explanations) is necessary
because there's no way to persuade the developers to clarify the
interface.
<<... and the procedural topics also link back to the associated
dialog topics.>>
That's also important, but it's a different meaning of "context": in
this case, the context has shifted to "how do I complete the current
procedure using the interface?". Both are important.
<<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.>>
Ideally, you must provide easy access to both kinds of context: an
overall context of how to accomplish a goal via tasks, and the
specific context of each task or procedure en route to that goal.
Robert Lauriston noted: <<The online help should be task-oriented
rather than driven by the UI.>>
Only in some contexts. <g> It's certainly true that modern
documentation should focus on goals and tasks, but we mustn't forget
that understanding the interface is the sine qua non for some tasks.
This is why we create "orientation" topics that explain the different
parts of a product and details of each part of the interface, and why
we provide field-level help. Effective help systems must do both: give
a high-level view of how to get from point A to point B, and a low-
level view of each component of 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.>>
I've used such topics very effectively to help people learn what
software can do and to provide links to details of the steps (tasks)
to accomplish ech of those goals.
<<- If not, link to the most common task and have cross-reference
links to the other tasks, or>>
Also very important, particularly for help topics that take the form
of "part X of Y". For example, such topics can begin with "before
completing this step, you should have completed [list of others steps
with links to their help topics]" and can end with "after completing
this step, here are some likely subsequent steps you'll want [need] to
complete [list of others steps with links to their help topics]".
<<- 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).>>
Agreed, with two caveats: First, group the tasks into task clusters
(e.g., all the tasks required to accomplish a specific goal). Many
help systems are nothing more than alphabetical FAQs that conceal the
larger picture. Second, you should also provide links to the nitty-
gritty details of each interface element that might require
explanation; at a minimum, those links should use the tooltip name to
link to an index entry for that element.
For example, with a database-linked application I once documented, the
original UI included only the classic Close buttons for most dialog
boxes; like many databases, changing a field and tabbing to the next
field saved the changes to that previous field. Until I was able to
convince the programmers to add a "Save changes" button, I included a
line in the docs that made it clear to users that moving to a new
field or closing the dialog saved the changes. Without that
explanation, this behavior wasn't clear to the users of the product
(no, really!), leading to considerable confusion.
<<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.>>
That's potentially a problem with the design of the popups rather than
the overall principle. But I haven't used Eclipse, so I can't say how
much of this is a UI problem.
<<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.>>
Precisely. The goal is to remember that if users must leave their
context (completing a task) to research some information in a new
window, that's a design flaw. We can take steps such as Robert's
suggestion to reduce the frequency and cost to the user of such flaws,
but often the better choice is to solve the interface problem and
eliminate the need to consult external documentation -- which includes
the help file.
------------------------------------------------------------------------
Geoff Hart (www.geoff-hart.com)
ghart -at- videotron -dot- ca / geoffhart -at- mac -dot- com
------------------------------------------------------------------------
Effective Onscreen Editing: http://www.geoff-hart.com/books/eoe/onscreen-book.htm
------------------------------------------------------------------------
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. http://www.doctohelp.com/SuperPages/Webcasts/
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! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
