Re: metadiscourse

[Peter Collins <peter -dot- collins -at- BIGFOOT -dot- COM>]

    Paul, Tim and Ben quite properly punched my tongue back out of the
cheek into which it had become so mischievously lodged.
    Of course you cannot wrote a help guide as an FAQ, of course FAQ
sections are not given appropriate structures for that function and of
course there is a world of difference between a user guide and a tutorial.
    In User Guides, I have never used Socratic discourse and I hope never
will. I hope never to be caught there writing "How do I ...?" or "How to X"
as a heading, for in the TOC (especially under alpha sort) or Index I
expect my reader to be looking for "X" and not for the obviously implicit
"How To". I try to cut out all such as "this section deals with ..." for if
required they show my heading is misworded. I avoid all closing summaries
as irrelevant for I believe my readers are working through my steps
(generally on-screen) as they read (and this is part of how my writing is
usually tested) so that at the end of the last step they have achieved
their success and proved their knowledge and have no need or desire to go
further.
    Our printed word lacks the inflexive cues of our spoken language, and
our thoughts flow differently when reading, for depending on our habits and
mental styles we can for example scan ahead and back or build a spacial
mental model of the page, whereas speech is absolutely linear. Good writers
and speech writers well know and exploit these differences. Poor ones turn
out turgid speeches and forgettable books. I hope one day to be a good one.
I do know that the need to 'orient' the listener is quite different for a
speech-maker than for a reference book reader who will have already a
well-formed mental focus of what they expect to appear on the page - if
only they can find the right one!
    Some technical publications comprise combinations of definitions, user
guide (variously accessed as context-help or 'ordinary' reference or by
linear reading), tutorial, trouble-shooting, usage techniques sometimes
categorised as basic or advanced, and (worked) examples. Good TOC, indexing
and just sufficient, highly relevant cross-references are essential. I find
it quite a challenge, even using hypertext links, to design for such a work
a structure that is accessible and easy to use for any level of reader, has
style appropriate to each section, and minimises duplication with its risk
of version skew between sections. Usually such a work is required to
function in print and on-screen both in HLP and HTML. I doubt some reader's
ability to get the right message from headings in the TOC and thus to be
confused when presented with both "Glossary" and "Definitions" so I try to
avoid such distinctions. But even then, the headings in a TOC, unless they
are worded almost as chapter summaries, are often poor guidance to an
ordinary reader as to where in the book they should turn for material of
the right topic and level for their immediate need. So though I have never
written one yet, I am coming to favour a "How To Use This ..." preface that
tells you what sections to read, in what order, for your need.
    "Horses for courses" is still the universal rule.
    I get plenty of criticism for my drafts. I am not one to preach, and
deserve what I get if I fall into that trap.
    Thanks guys
P
========================================================
Peter Collins, VIVID Management Pty Ltd,
26 Bradleys Head Road, MOSMAN 2088, Australia
+61 2 9968 3308, fax +61 2 9968 3026, mobile +61 (0)18 419 571
Management Consultants and Technical Writers
email: peter -dot- collins -at- bigfoot -dot- com                ICQ#: 10981283
web pages: http://www.angelfire.com/pe/pcollins/
========================================================


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=