atw: Re: austechwriter Digest V7 #115

Geoffrey,
I generally agree that a lot of redundant words can be pruned from a lot of
writing.
A set of headings that use the format
  How to cook a gerund
  How to catch a gerund
  How to do something silly
  How to make a list hard to scan
is really difficult to scan.  It can be read, but you do have to read each
line.

if you prune to 'How to' part you get a scannable list:
  cook a gerund
  catch a gerund
  do something silly
  make a list hard to scan

But the list is still not really easy to scan.  We need to put the key word
up front.
With headings in a chapter, the same subject is repeated.
With a chapter heading, you can prune it back to the keyword.

  Gerund - How to cook
  Gerund - How to catch
  Silly - How to do something silly
  Scan - How to make a list hard to scan

This is where Geoffrey's neatly pruned chapter headings (titles) helps a
lot:

Gerund
   Cook a gerund
   Catch a gerund
Silly
   Do something silly
Scan
   Make a list hard to scan

------------ -
Making sure at every step of the way.

>>  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.  <<

I have come across this idea of having to reinforce the issue at EVERY step
just to make sure.

What started out as a set of simple steps of a process, can become a huge
mass of text that I think has begun to defeat the purpose.
1  do this
2  do that
3  at the Whatsis menu, select Whatsis
4  Click OK
5

. of the document.




2009/5/23 HILCHER <hilcher@xxxxxxxxx>

> 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
>> ***********************************
>>
>>
>


-- 
Bob Trussler
Phone  0418 661 462

Other related posts: