Gerunds always in headings for online help?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Jim Hager wrote to inquire about: <<Gerunds Always in Headings for Online
Help?>>

"Always" is a dangerous word. Although gerunds are useful for actions, you
obviously don't have to change the table of contents title to read "tabling
contents" or the reference section to read "referencing". So as a first step
in answering your question, you can start by limiting gerunds to topics that
aren't truly actions; "looking up definitions" should be "glossary",
"finding topics in the manual" should be "index", and so on.

That's obvious enough to be a bit insulting, which isn't my intent; the real
issue is that it introduces a key distinction: between actions and tasks on
one hand, and conceptual or overview information on the other. You don't
need to use gerunds for the latter in most cases  because the topic (e.g.,
overview of maintenance procedures, how the five menus link together) is
made up of many tasks that each benefit from a gerund heading.

<<For years, just like most other tech writers, I've been using gerunds as
the standard for headers, as in the following: - Getting Started - Adding a
User...>>

And that makes good sense. It both expresses the concept in the same form
that readers are thinking about it, and follows long-established practice.
Thus, it has the benefit of familiarity.

<<When I look at the the resulting online help, with its 500 or so topics
(one per heading), I think that it is not easy for the user to
scroll and find the topic they are looking for because there might be 20 or
so topics starting with the same gerund.>>

That's a perfect situation for two simple solutions:
- a miniature table of contents: e.g., the first item might be a link named
"creating" that, when clicked, takes readers to a list of all the things
they can create
- skilled use of subheadings: If you don't want users to jump off the
current page, then unite all the possible forms of "creating" under the
heading "creating" and delete the word "creating" from the list of links
under that heading.

Both solve the problem by helping users scan until they find the category of
action they're seeking; if they're seeking information on creating something
and you have dozens of "printing", "saving", "verifying", etc. topics, they
can ignore all the sections prefaced by the heading (or TOC link) and jump
directly to the heading for creations. If necessary, further subdivide the
topic; for example, "creating-->squares-->with the pen, with the square
tool, by scanning in square objects". (The last three are indented under
"squares", just as "squares" is indented under "creating".)

<<Even if they use on index search or a text search, they will get lots of
matches on some gerunds used many times.>>

They shouldn't really be _searching_ an index, other than by scanning
alphabetically down the list; any good index will present the main keyword
(e.g., creating) with an indented or run-in list of secondary keywords, and
a good indexer will choose secondary keywords that are distinct and easy to
separate. As for searching, my feelings on this are plain: a search tool is
the tool of last resort when all else fails because of how ineffective
searches usually are. Don't rely on it to help users find information. Give
the technology another 5 years to mature and I may change my opinion.

<<The bottom line is that the user is really looking for the Product
Maintenance, not Maintaining Product Information. They are really looking
for Inventory Search, not Searching for an Inventory Item.>>

Here, the problem is that the heading "product maintenance" should introduce
a relatively broad overview of this subject area, with explanations of the
various tasks and how they relate to each other. The reader knows that they
want to maintain the product, and need only learn one of two things
(depending on their knowledge): the list of all tasks involved in
maintenance, or how to do each task.

"Maintaining" a product in your database is probably not an actual task:
finding the product, updating its parameters, saving the changes, and so on
are probably the actual tasks performed under maintenance. So don't send
people to "maintaining products"--send them to the actual tasks, or to a
"product maintenance" overview if they don't know what tasks are necessary.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"When ideas fail, words come in very handy."--Goethe

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at
http://www.ehelp.com/techwr

  Check out the TECHWR-L Site redesign! 
  http://www.raycomm.com/techwhirl/

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.