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.
Jeff Scattini wondered: <<I'm currently writing a series of
task-oriented documents for a software application. I learned that one
should always put the user-imperative at the beginning of each step: 1.
Click Start on the toolbar... However, one of my product managers wants
to bury the imperative in surrounding text: 1. On the left-hand side of
the toolbar, click the Start button.>>
Which is better depends on your audience. The advantage of putting the
navigation information up front is that new users need this information
because they haven't yet learned where to look. The problem is that
phrases such as "left side of toolbar" require the reader to construct
a mental image of what the toolbar looks like, then seek that mental
image somewhere on the screen. That's less of a problem for menus, of
course, since the word used in the procedure can match the word used in
the interface.
Conversely, putting the navigation information ahead of the actual
instructions justifiably annoys skilled users of the software, since
they already (largely) know where to look. Why make them read twice as
much text if it's not necessary? Best to simply eliminate this
information entirely for their sake... but then, what about the poor
newbies who need it?
The solution for both users is simple: combine text with graphics. In
the text part of the instruction, state only the imperative. "Click
Start." Then accompany this with a graphic at the right that shows an
actual picture of the thing that must be clicked or the location in
which information should be typed or selected. This provides the
missing support for those who need it, and doesn't force them to guess
what visual image they should be seeking (particularly important for
obscure icons with no obvious textual description). Those who don't
need it can simply ignore the graphic.
Of course, this can get messy if you have many procedures that require
reference to the screen images. In that case, an elegant and effective
solution is to provide a single screenshot, with the instructions
arranged neatly around it in a logical order (e.g., clockwise from top
left). That way, the instructions are tied directly to the images
readers need to look at to know where to do things--and the pros can
still ignore the image and focus on the words.
But what about simple things like clicking on the Start button? For
some of this, you can get away with the standard "We assume you already
know how to use Windows" assumption. After all, it's kind of messy and
expensive having to add 500 pages of Windows documentation to your
500-page product manual. How can you know what to omit? Ask the users.
They're the ones who can tell you.
Now Shipping -- WebWorks ePublisher Pro for Word! Easily create online
Help. And online anything else. Redesigned interface with a new
project-based workflow. Try it today! http://www.webworks.com/techwr-l
Doc-To-Help 2005 now has RoboHelp Converter and HTML Source: Author
content and configure Help in MS Word or any HTML editor. No
proprietary editor! *August release. http://www.componentone.com/TECHWRL/DocToHelp2005
