RE. Menu- or function-driven software manuals?

Subject: RE. Menu- or function-driven software manuals?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "Techwr-L (E-mail)" <TECHWR-L -at- lists -dot- raycomm -dot- com>
Date: Fri, 19 May 2000 10:59:04 -0400

Donald Timmerman observes that <<...most of the software user manuals I've
seen are usually organized in such a way that the software is the driving
force for the way the procedures are presented (i.e., all the procedures are
presented as a function of the menus and commands). For example, the
procedures are usually listed under menu and command headings. I have seen
fewer examples of manuals that are organized in such a way that the software
functions are the driving force for the way the procedures are presented
(i.e., all the procedures are listed alphabetically by user function). For
example, procedure heading may look like the following, which in no way
resembles the software menus and commands: Create a Commodity Set... and so

The distinction you're observing is between reference manuals ("I already
basically know how to use the software: just tell me what the following
seldom-used menu item does") and user manuals ("I don't know how to use this
software, and need you to tell me where to look in the menus"). The modern
trend is strongly away from primarily reference manuals and strongly towards
primarily task-oriented ("user") manuals simply because as a profession,
we've recognized that we have to provide support information that helps
people work with our products (i.e, perform "tasks", not look up information
on menu choices). The naming distinction relies on the difference between
those who "refer" to the manual and those who "use" it.

As someone who creates such manuals, you have to begin the creation process
with a clear knowledge of whom you're writing for and how you expect them to
use the manuals. If you're confident that they'll only use the manuals as a
supportive reference, much the way we writers use dictionaries, then a
reference structure is perfectly appropriate. For example, software
development kits are produced primarily for programmers who already know how
to program, and who mostly require some form of way to look up the detailed
syntax of an unfamiliar command. Conversely, a general-purpose tool such as
Microsoft Works is designed for people who may not know what they can or
should accomplish with the software, and the most important goal is teaching
them how to _use_ the interface to accomplish tasks. That suggests a user
manual is more appropriate.

Of course, neither situation is purely black and white, and in neither case
should these be the only types of information you provide. For example, the
programmers may need to learn how to use a new debugger efficiently, whereas
Works users may need to look up the syntax for visual basic macros. Striking
a good balance between the primary and secondary goals of documentation can
be tough, and it requires good audience knowledge.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca

"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer

Previous by Author: RE. An Engineer has infected my young mind!
Next by Author: RE. Graphics instead of words?
Previous by Thread: Re: Menu or Function Driven Software User Manuals
Next by Thread: Requirements in Phases

What this post helpful? Share it with friends and colleagues:

Sponsored Ads