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.
Jamie Peffley wondered: <<I was taught to word headings as gerunds* and
to be consistent: Using the Whatsis, Working with Thingies, Creating a
Whosit. We have employed this throughout our documentation, sometimes
be very creative for non-action type topics to have a gerund
(Understanding Zoobles).>>
* Possibly a gerundive, actually. I can never remember the difference.
This is a standard solution because it works, and works well. In
particular, it focuses on the task (what the user is trying to do)
rather than on the interface feature, and that's always the best way to
structure information. Alternatives such as using infinitives work less
well because you end up with a wall of "to" phrases in a table of
contents or alphabetical listing instead of alphabetizing based on the
gerund. Nominalizations don't work because they provide no clue about
the action.
<<Recently my team of writers and I learned... that this was
old-school, and you shouldn't force topics into a non-action, gerund
syntax.>>
Huh? Breathing, eating, and many other -ing phrases are so terribly
quaint and old-school, but I wouldn't plan to give 'em up just because
they're old. <g> Beware soi-disant experts who recommend a change just
because something is "old". In short, don't fix it if it works unless
the advisor can provide compelling evidence--either experimental data
or a logical explanation--that the new method truly represents an
improvement. Often (cf. Microsoft Manual of Style), you're only hearing
opinion masquerading as fact.
The key part of the statement is "force topics into a non-action
syntax". If you focus on the task, no forcing is required: the gerund
choice becomes natural. And gerunds are not non-action syntax: they
represent the action.
<<So instead of Understanding Zoobles, I could just say...Zoobles.>>
Which would tell me precisely nothing about the contents of that
section, suggesting that this isn't a good choice. What about Zoobles:
which of the 1000 potential aspects of Zoobles will the section
discuss? "Understanding" tells me that this is an introduction;
"Zoobles" tells me nothing.
<<...instead of an overview topic: Understanding Synchronization
Between Your Desktop PC and PDA, we'd have something like:
Synchronization Between Your Desktop PC and PDA (and before you say,
why not Synchronizing Your PC and PDA, it's because this is an overview
and the procedural topic is called Synchronizing....).>>
This example illustrates a different problem: the overview and the
procedural topic should not be separated. The overview tells me what I
need to know before I synchronize, and I can skip that step if I
already know it. The procedure tells me--now that I know the
context--how to operate in that context. The instruction is incomplete
if the two are separated.
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.componentone.com/TECHWRL/DocToHelp2005
