Consistency in headings?

Subject: Consistency in headings?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>, "Peffley, Jamie" <Jamie -dot- Peffley -at- sage -dot- com>
Date: Wed, 22 Mar 2006 15:06:10 -0500

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.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


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!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Consistency in headings: From: Peffley, Jamie

Previous by Author: Avoiding "Uninstallation"?
Next by Author: Subject: Re: Consistency in headings
Previous by Thread: Re: Consistency in headings
Next by Thread: RE: Consistency in headings

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

Sponsored Ads