atw: Re: austechwriter Digest V7 #115

Sorry about that.
I was just waffling to myself, and putting ideas together.

Must have slipped and pressed SEND.
Bob T

2009/5/31 Bob Trussler <bob.trussler@xxxxxxxxx>

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



-- 
Bob Trussler
Phone  0418 661 462

Other related posts: