atw: Time for another debate?
- From: "Geoffrey Marnell" <geoffrey@xxxxxxxxxxxxxx>
- To: <austechwriter@xxxxxxxxxxxxx>
- Date: Sat, 23 May 2009 13:57:45 +1000
Hi austechies,
This list has gone deadly quiet of late, so how about a new debate? What
about one on the format of chapter titles in user guides.
Although not universally the practice, it seems that most technical writers
(TWs) cannot resist constructing chapter titles in the form {present
participle + noun}. For example:
* Entering bookings
* Using reports
* Working with tables
The first word in these examples is a present participle (the -ing form of
an underlying verb: enter, use and work). Some folk call these introductory
words gerunds, but gerunds, although also taking an -ing ending, are formed
from nouns, not from verbs. The gerund equivalents of the examples given
above are "The entering of bookings", "The using of reports" and so on.)
Happily, TWs don't use the excruciating gerund form for chapter titles, but
why do we feel the need to include the present participle? Why don't we just
call these chapters:
* Bookings
* Reports
* Tables
I've asked a couple of senior TWs this question and their view is that an
action word in the title makes it clear that the chapter is telling us how
to do things, not just giving us facts. But the fact that the entire
document is called a user guide or user manual is already telling us that it
is primarily about how to do things, namely, using a product. It might have
some referential material in it (say, a list of error messages) but such
material has a traditional and expected place in a user guide: in the
appendixes. Referential material goes into appendixes; procedural material
goes into chapters. That's been traditional publishing practice for yonks.
No TW following standard practice sandwiches a chapter of referential
material between two chapters of procedural material. Hence there doesn't
seem to be a need for any special flag in the title of a chapter to tell the
reader that this particular chapter is about how to do things. The context,
and traditional publishing practice, says it all.
So the {present participle + noun} form seems unnecessarily verbose in a
user guide. (What does "Working with tables" tell you that "Tables"
doesn't?) Further, it forces the TW into either truncated specialisation
(calling a chapter "Entering bookings" when it is also about changing,
cancelling and printing bookings) or imprecise abstraction (what does
"using" or "working with" really mean?: just doing things with?). In a
manual that is primarily about how to do things, it seems a waste to keep
reminding the reader that a chapter is about how to do things.
Moreover, does anyone actually read chapter titles? I doubt if more than a
few do. The way a typical user typically uses a user guide is to consult the
index and then jump straight to the topic or task they need help with. A
chapter title is at most a blur during thumbing. Why, then, do we fuss over
something that most uses never read and, for those who do, the meaning would
be quite clear without any leading participle or participle phrase?
So, is there any logic to our practice of naming chapters in the {present
participle + noun} form? Or do we do it simply because we have always done
it?
Let the games begin.
Geoffrey Marnell
Principal Consultant
Abelard Consulting Pty Ltd
T: +61 3 9596 3456
F: +61 3 9596 3625
W: <http://www.abelard.com.au/> www.abelard.com.au
Other related posts:
- » atw: Time for another debate? - Geoffrey Marnell
