atw: Re: Time for another debate?

1.  I read the content pages (chapter titles), always.  If I have to go to
an index to find the information I need from a plain old user manual then
they've done a poor job of the titles as well as the chapter content.  The
exception is recipe books.

2. Yes, the traditional heading form is redundant.  Very often not even
accurate, as you've noted.  One could get quite pedantic (which I'm rather
inclined to do) about "using reports", for example, since the guide has yet
to be written for instructing anyone on how to "use" reports.  At best, user
manuals tell people how to generate and present reports.  The uses to which
reports are put, or not, is a more mysterious matter.

3. I have to confess that I get rather rabid about headings, as used in the
wider world of business.  For example, when I see "Table of Contents" I tend
to start foaming at the mouth.  The consequences are much the same when I
see a heading such as "Purpose", following by a sentence that begins "The
purpose of this document ..."; or "Audience" ..."The audience for this
document is ... " Arrrrhhhhhhh!

See Geoffrey, there are bigger, more mind numbing, fish to fry when it comes
to superfluous verbiage in business.

User manuals are probably the more innocent party, since most people never
look at them again once they walk out of a training room, therefore, the
damage is minimized.

C.H

On Sat, May 23, 2009 at 1:57 PM, Geoffrey Marnell
<geoffrey@xxxxxxxxxxxxxx>wrote:

>  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: www.abelard.com.au
>
>

Other related posts: