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.
Chris Orr wondered: <<My documentation team has a thorny problem with
our product's new UI. With the new UI, users can choose how they want
to view the product, and items appear in different folders and menu
structures, according to the chosen view. Additionally, users can
create new views. We do not know how to direct users to find the items
mentioned in procedures.>>
One huge advantage of embedding the help is that each different
interface view is accompanied by its own help. This process can be as
basic as providing tooltips for every item that appears on the screen
or as complex as dynamically generating help screens based on the
contents of any interface screen. (No idea how you'd do that, but
fortunately Char James-Tanny is part of techwr-l and can point you in
the right direction.)
<<We have tentatively decided to provide no UI navigation info in the
procedures but instead provide a comprehensive UI navigation section in
our Basics chapter. But we are concerned that users may find the
procedures they need, but not go on to use them because they can't find
the items mentioned in the procedures.>>
The harder solution is to break down the problem into its "atomic"
elements. These are the smallest tasks and related chunks of
information that are meaningful to the user and that have a clear
counterpart in the interface. If you can document this information,
that forms the core of your procedure. You can then create
documentation that says something like the following: "Here's what
you're trying to accomplish. You can do this in any of the following
ways:" The list then becomes hyperlinks to each of the different ways
to perform that specific task or use that specific feature.
For icon-heavy interfaces, present a visual glossary so users can click
components of an image map and jump to the description of each
component.
It's also useful to do what you have suggested: provide an overview of
UI navigation. Make this part of the online help system so that you can
cross-reference this help topic from every other topic where this is
relevant.
<<Whatever solution we decide on, it must work for us in a highly
dynamic development environment, where we maintain hundreds of
documents and localize them into many different languages.>>
This suggests that you need to consider some form of single-sourcing.
One advantage of breaking up the information as I suggested above would
be that it facilitates single-sourcing.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
