atw: Re: Time for another debate?

Hi Geoffrey,

With respect to your query about the 'present participle + noun' form of 
heading, I suspect you will find it comes from the Competency-based learning 
[CBL] approach, which mandates that each heading must have something that looks 
like a verb and its target. With this style of heading, when someone has 
learned you can use a past participle to designate competence - efficient, 
ain't it? When I started learning engineering, all headings were just the name 
of the object / concept about to be described, analysed, criticised, eg, 
turbine principles, blade angle vs shaft speed, bearings, lubrication ... I 
have miniscule sympathy for the CBL approach - would you like your heart 
operated on by someone who was merely 'competent'? Bring back excellence, I say!

I agree that there is no need for such redundancy as 'Table of' Contents, 
'Schedule of' Figures, 'List of' tables - all a 'Source of' Toilet Paper. I 
think chapter headings and other, apparently silly introductory words are often 
put there because that's what the client put in the contract as a deliverable, 
and you want the grand paymaster to see that you have complied, so that the 
strange ritual called 'payment for services rendered' will repeat.

However, I think there can be a case for repetition. We cannot mandate how a 
reader should find relevant material in any document. At the beginning of many 
user docs, I tell the reader not to read this doc like a novel - treat it as a 
reference - go where you need or want. Because readers have many different 
levels of skill, we can only guess vaguely what a particular reader may need; 
hence, I believe that we should provide many pathways, including repetition. 
For instance, if you provide hyperlinks within your doc, a reader may avoid the 
Contents or Index pages altogether, may browse or drill down till something 
looks relevant and then just follow links - without ever seeing chapter 
headings. In one instance, I used a series of system diagrams, each linked to a 
more detailed diagram eventually ending, in some cases, in a word-based 
description. This 'peeling of the onion' method reduced what had been over 1000 
pp of engineering instructions to an 88 pp doc.

If I know I am writing for absolute beginners, I may avoid links at first, and 
may repeat material so the whole of each instruction is in one contiguous lump 
- even if that means re-using that stuff about formatting paragraphs / fonts 
... 

When I first started in Tech Writing [motor vehicle assembly], there was no 
user documentation - if any existed, I wrote it, because I had analysed the 
work process. When I returned to Tech Writing more recently, I used to search 
the user documentation - often in vain - for how to do something. Other members 
of the team who had been on the training course - not I, because I had joined 
after the initiatrix, who could no longer afford to send people on courses - 
would quietly point to the date on the user documentation title page and the 
date of the software in the Help About section on-screen; I had been given an 
out-of-date copy of the user documentation because no-one would part with a 
carefully annotated personal copy. So, I learned to use the drop-down menus and 
the built-in Help - which is also often out of date, but not by so much as the 
hard copy. 

Consequently, in answer to your question about whether I prefer to look in the 
Contents or the Index, my simple answer is 'No'.

Cheers,
Brian.

Other related posts: