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 provided more information: <<... this is a web-based product>>
That makes it easier to dynamically generate Web pages on the fly; I'm
sure this can be done on the desktop too, but don't know the equivalent
technologies. On the Web, "Active Server Pages" (.asp files) are one
example of such technologies. I know next to nothing abut them beyond
the acronym, but they're widely used.
<<embedded help would solve some of our problems. But what about the
scenario where a user finds a procedure in the help file and then needs
to go do the procedure in the product?>>
See my previous postings (last week?) about how I created tutorials
when I had no access to more sophisticated procedures such as wizards.
The short version is that your first step must be to separate the task
description from the interface description. For example, one of my
standard approaches to creating a help topic was to create a single
topic that listed the overall sequence of steps required to accomplish
a task, then separate this from the details of the steps (i.e., the
interface description), which are reached by means of hyperlinks. The
overall topic tells you what to do to accomplish your goals; the linked
topics show you each possible way to accomplish this.
The simplistic explanation of the solution is something like the
following, with hyperlinks underlined: "To prepare your expense account
report, you need to do three things: 1. Create a new spreadsheet. You
can do this by _clicking the New account icon_, _selecting New account
from the File menu_, or...." Then repeat this for steps 2 and 3.
Alternatively, provide a single hyperlink per step that leads to a
topic that discusses all alternatives: "You can accomplish the New
account function in three ways, each of which is described later on
this page. [list of the possibilities, each of which hyperlinks to a
point later on this same page]
The basic principle here is that the hyperlinks go to a topic (or
subtopic on the same page) that shows what the interface looks like for
each alternative and how to use that part of the interface. The "how
to" information that relates to the actual procedure would then be
supplemented by details on that aspect of the task. In a dynamically
created Web page, for example, the first lines of the page would be
taken from a file or database entry that describes the UI for this
specific function, and the last lines of the page would be taken from a
file or database entry that describes the procedural details.
<<If they don't know where to go, there's a problem.>>
It's (y)our job to tell them where to go. <g> Users get confused by
having too many options (it's called "the paradox of choice"), so one
of our roles is to simplify that complexity by telling them which
option we recommend. Other options may be equally acceptable, but
that's not the point: the point is that we must simplify things for
those who need the simplicity of a single option, while noting that
alternatives are available for those who don't like what we recommend.
Just hide those options behind a link so that nobody is paralyzed by
choice.
<<... we are changing our target user profile from near-moron to
sophisticated computer user. But our product is notorious for bad ui
and difficult navigation. Hopefully, the new ui will be a real
improvement, but I am not convinced yet.>>
One standard solution is to pick what you consider the easiest to use
or most efficient or easiest to understand approach, and document that
approach everywhere as your preferred choice. For example, most
computer documentation focuses on the sequence of menu choices because
that approach will work for every user in every context. The docs then
add such things as keyboard shortcuts in the margin, or provide "expert
topics" that supplement the menu-based approach. It's easy to produce
such help by listing the "everyone can succeed by following these
steps" information first, and offering a link to one or more
alternatives for those who dislike your primary description.
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
