atw: Re: austechwriter Digest V7 #115

Personally I believe it is dependent on the use of the material.

Technical information pertaining to standards etc. are more suitable to not
including the present participle.

I would however believe action material such as training is more suited.
Primarily because of the need of the reader (under stress and needing info
NOW).

On Sat, May 23, 2009 at 1:58 PM, FreeLists Mailing List Manager <
ecartis@xxxxxxxxxxxxx> wrote:

> austechwriter Digest    Fri, 22 May 2009        Volume: 07  Issue: 115
>
> In This Issue:
>                Time for another debate?
>
> ----------------------------------------------------------------------
>
> From: "Geoffrey Marnell" <geoffrey@xxxxxxxxxxxxxx>
> Subject: Time for another debate?
> 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
>
>
>
>
> ------------------------------
>
> End of austechwriter Digest V7 #115
> ***********************************
>
>

Other related posts: