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.
Johanne Cadorette wonders: <<What's the word on using gerunds in headings in
technical documentation?>>
It's a common and often appropriate style. The rationale behind using a verb
form is that it focuses on doing something, and the goal of most procedural
docs is to show people how to do something. Using a noun phrase or something
similar focuses more on describing the product than the proces. For example,
when I see "Titling chapters", I expect to learn how to apply a title to a
chapter; when I see "Chapter titles", I expect a long and boring description
of the zen nature of the chapter title. The noun form might be more
appropriate in reference material where the goal is descriptive; for
example, in a chapter entitled "Illudium PU-36 Space Modulator"*, I expect
to learn all the technical details about this particular device and how to
protect it from rabbits.
* Hi, Janice. <g>
<<In our guides (administration and installation guides for the system),
most of the headings contain gerunds ("Creating Transfer Entries,"
"Exporting Report Data," etc.), and we're finding that this sometimes makes
the headings needlessy cumbersome.>>
Personally, I think those headings work quite well and tell me exactly what
I'll find in the chapter. I'm not strongly convinced that avoiding the
gerund would be outright wrong (readers often fail to notice some of the
things we obsess over), but it's not my preference. You do, however, have to
consider playing to the expectations of your audience. If docs in your
industry all use gerunds, it's probably wise to follow suit so that your
docs read like everyone elses. Better written, of course, but similar enough
in style that there's no culture shock when they read yours.
<<There are times when the gerund isn't really what's important ("Setting
Post-Audiotex Behavior," for example. Who cares about "setting? in this
case? It could be any other similar word like "determining," "assigning,"
etc.)>>
"A foolish consistency is the hobgoblin of little minds, adored by little
statesmen and philosophers and divines."-- Ralph Waldo Emerson
(_Self-Reliance_). The goal of consistency is to communicate similar
concepts in a similar manner. If the goal of the chapter changes, sticking
with a gerund for the sake of seeming consistency is no longer relevant. But
ask yourself: what the chapter is really about. If it's describing a task
(e.g., "dealing with the behavior", "knowing when the behaviour represents a
problem"), then you need to consider using a gerund that communicates this.
If the chapter simply reports a huge expository dump to reassure readers,
the gerund's probably not necessary.
<<What's more, when these headings are translated into French, they end up
being soooo long that we have to change the French anyway.>>
That strikes me as odd, except of course that French is inherently typically
15%+ longer than English. But if my chapter title were "Creating", I'd
translate that as "Creation de" (insert accents!) in French, and that's only
3 letters longer based on the gerund translation. In any event, part of
translation is explaining the same concept in the new language's own idiom,
and French idiom may differ slightly; I'm afraid that I don't read any
French docs other than the ones we produce, so I can't claim to be expert.
<<We're wondering... whether it's some kind of tech writing standard we're
not aware of.>>
Heh. ISO 9000-23. Look it up if you don't believe me. <g> Seriously, though,
there are _no_ technical writing standards. Lots of rules of thumb and
generally accepted practices (including gerunds in headings), but no
standards yet, thank God. Most of us still have the freedom to use what
works, and change what we use when the situation demands it.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The skill of writing is to create a context in which other people can
think."--Edwin Schlossberg, designer (1945- )
Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at http://www.ehelp.com/techwr-l
---
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.
