atw: Re: Time for another debate?
- From: "Brian Clarke" <brianclarke01@xxxxxxxxxxxxxxx>
- To: <austechwriter@xxxxxxxxxxxxx>
- Date: Sun, 24 May 2009 16:48:54 +1000
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:
