Re: Metadiscourse

[Ben Kovitz <apteryx -at- CHISP -dot- NET>]

Mike Stockman replied to my discussion of metatext, pointing out that
people often respond well to a structure like this:

>**Creating a Customer Account**
>(Here's what we're going to do:) This section describes how to set up a
>customer account, including the customer's contact information,
>purchasing preferences, and favorite colors. Once the account is set up,
>you can use it to sell the customer many expensive prodoucts.
>
>(Here's how to do it:) Step 1: Enter the name... etc.
>
>(Here's what we did:) The customer account is now complete. You can now
>use it here, here, or there. For more information, see these other places.
>
>That pattern (what we're about to do, how to do it, what we just did) has
>always served me well in classes as a way to reinforce the message. Of
>course, I dump that structure where it doesn't apply or will be too
>cumbersome, but it's a good guideline. I've also used it many times in
>writing manuals and tutorials, with positive results.
>
>So my question/point is, doesn't "metadiscourse," if used properly, serve
>this "bracketing" purpose to help the message get through?

Really good example--thanks for posting this!  I totally agree.  But notice
that your metatext is more than just metatext.  You aren't simply repeating
the heading.  You're giving information about the subject matter itself, in
the form of an overview.  You're telling the reader what are the main parts
of creating a customer's account and why this is useful, not just saying,
"This section describes creating a customer account", which by itself would
serve no introductory purpose that isn't already served by the heading.  I
probably wouldn't word it as "This section describes..." but that's only
because I've gotten jumpy about that kind of sentence after seeing it
abused so much.  In the above context, where it's providing introductory
content, it works beautifully and doesn't bug me at all as a reader.

Someone off-list mentioned that little tables listing major or related
topics and where to find them are another good sort of metatext.  (Like
"See these other places.")  I totally agree with that, too, and I do it all
the time myself.  A few technical writers find it strange, but I think
those tables are very handy for readers.  I mention in the book that things
like TOCs and overviews of the structure of large documents are examples of
genuinely useful metatext.  One of the example documents even contains a
little table of related stuff to see elsewhere in the document.  These
little tables are like signposts on a road.  Naturally a road should be
mostly road and not signposts, but a few signposts at strategic locations
are indispensible.

I wouldn't want to make a total injunction against metatext (I didn't think
I had).  But I think that in common practice, it's one of the easiest
temptations for people who just want to write some text but don't want to
research the subject or don't want to think about what might be useful to a
reader.  I've seen sections that were *mostly* metatext, and entire pages
given over to repeating, in narrative form, what was already written
clearly on the title page.

Here's an abbreviated example.  Title page: "Datablaster 2.0, by Splenetix
Corporation.  23-Oct-98."  First page: sections like "1.0 Purpose and
Scope. The purpose of this manual is to describe release 2.0 of
Datablaster.  1.1 Manufacturer. The manufacturer of Datablaster is
Splenetix Corporation.  1.2 Date of Release. This release of Datablaster
(Release 2.0) was released on October 23, 1998."  And so on.  You see
*tons* of this sort of gobbledygook in internal documentation, such as
requirements documents.  Those documents are technical writing no less than
user's manuals, but serious technical writers seldom help in their creation.

When you have thought about what would be useful to a reader, and really
found that metatext is just what a reader needs, by all means include it.
But I think it's wise to always think, before writing some introductory
metatext, "Could I present some introductory content instead?  Or would the
content be made clearer by omitting this text entirely?"  Some metatext
passes this test, but a lot that I've seen doesn't.

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Boulder, Colorado


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