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.
I've created my documentation to meet the needs of several types of
users: those who want and in-depth understanding of the entire product
workflow; those who want to understand the workflow for just part of the
product; those that want to understand just a particular field, term, or
concept; and those who aren't sure what exactly they need to know but
who are looking at a GUI and wondering WTF?
Our product comprises several tabbed GUIs, each responsible for some
part of the Information Lifecycle Management (ILM) process and
infrastructure. For example, one GUI defines storage vaults and media;
another defines data ingest polices; and another defines data movement
policies. To create an ILM system from scratch, the user would use
several different GUIs in pretty much a pre-defined order. Later, to
expand or modify his system, the user would employ individual GUIs as
needed. For example, if the user wanted to tweak just his data ingest
policies, he would use just the GUI dedicated to creating and managing
data ingest policies.
Within each GUI, we provide hover help and three additional help
options: "Table of Contents," "Overview," and "Current Page." All three
link to the same browser based on-line help (but in different ways).
"Table of Contents" links to the overview of the entire ILM workflow
with which the documentation begins. "Overview" links to the overview
section for the given GUI the user has open. This section includes an
overview of the workflow for the given GUI, how the GUI fits into the
overall product workflow, and links to specific help pages for
individual GUI tabs. "Current page" links to the page in the help that
documents the GUI tab the user is currently using. Each help page
includes an overview of what a user can do and why, in relation to
overall workflow, they'd want to do it.
I've structured the help so that the user can understand workflow and
work through tasks by simply reading the TOC from top to bottom. Section
titles also include GUI names so that a user can browse to the section
for any GUI without needing a clear idea of the task they might want to
accomplish with that GUI.
In short, the help is task centric AND application centric. Along with
documentation for particular GUIs, tabs, and fields, it features an
abundance of overview and in-depth information for users who want to
understand the big picture. It also includes terse "How To" sections,
for users who want to be led through a task as quickly and painlessly as
possible, as well as tutorials. And of course, the help also features
search functionality and an index.
Leonard
-----Original Message-----
From: techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+leonard -dot- porrello=soleratec -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of McLauchlan, Kevin
Sent: Monday, May 10, 2010 10:33 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Context-sensitive - menu-item topic or... Clippy?
Is there a happy medium?
A lot of so-called "context-sensitive" help seems to be little more than
a link from a menu item or dialog to a page about that menu item or
dialog.
That's fine, as far as it goes, if you really need help figuring out
menu items or dialogs. And that's no small thing, when a dialog makes
assumptions about what you are doing and how you got there, and that you
understand the terminology. Having a page that expands the terminology
and translates it, and gives some clue about the outcome(s) of each
option and entry, can be of enormous help.
But it's a long slow slog if you know you want to accomplish something,
but aren't sure where to start, what the program calls that
task/operation, how the task (if it's even possible) is broken out among
menu items and dialogs, etc.
At the other end of the spectrum was the much-beloved Clippy....
How do you real-life authors deal with getting the real Help to the user
- the kind that helps them figure out what they are trying to accomplish
and how they should best approach it, as opposed to the kind that tells
them what the fields are for in the Print dialog?
Is it as simple as having additional links at the bottom of the page
that opens when the user clicks [F1] while a dialog is open?
Or do y'all have more sophisticated strategies? What might some of
those be?
I'm in the position of having created stand-alone WebHelp for several of
our products, anticipating the day when we'd move to a GUI. That day
looks closer, so I'm taking more interest in blending my existing Help
with the dialog-connected context help I would be creating.
Kevin McLauchlan
Senior Technical Writer
SafeNet, Inc.
--
Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial: http://www.doctohelp.com
- Use this space to communicate with TECHWR-L readers -
- Contact admin -at- techwr-l -dot- com for more information -
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
