Metadiscourse

Subject: Metadiscourse
From: Ben Kovitz <apteryx -at- CHISP -dot- NET>
Date: Thu, 22 Oct 1998 21:44:06 -0700

Doug Nickerson wrote, about learning from other people's documentation:

>One area piques my interst: how an
>author handles what Joseph M. Williams [1] calls "metadiscourse" (writing
>about the writing).
>
>For example, "In this section, I talk about this, then I discuss that."

Funny that you should bring this up. I call it "metatext" and
it's one of my pet peeves. In documents produced within
particularly bureaucratic organizations, I've seen documents that
were about 50% metatext. An easy way to clean up bloated,
boring manuals that no one wants to read is to go in and carve
out the metatext. I think it's almost always a cop-out, more an
attempt to "look busy" than to say something useful to a reader.

I just had a book published about how to write requirements
documents, which includes a little bit about metatext. (Links
are in my .sig below.) I'm going to see how the publisher feels
about making that chapter available on-line for free. (That
chapter only contains about two pages on metatext, so I wouldn't
recommend buying the book for that reason alone.)

My approach to metatext is that it's much better to write
"introductory content" than to talk about the document.
Sometimes metatext is necessary, but it should be a last resort,
only when you can't see any other way to help a reader interpret
the following text correctly. Introductory content is
fundamental information about the subject matter of a section
that helps a reader understand the information that comes
later. Notice that it's information about the subject matter,
not about the section.

The two most likely candidates for introductory content are
definitions and an overview. A definition says what you're
talking about, in effect providing a hook on which the reader can
hang everything you say later. An overview says the same thing
as what comes later, but in less detail, bringing macro-level
relationships into focus.

Metatext:

2.1 The Job View Window

This section describes the Job View window.

Introductory content:

2.1 The Job View Window

The Job View window displays and lets you edit all information
pertaining to a job.

This is an example of the "overview" style, though you could also
say it's a definition because it distinguishes the Job View
window from all others in the system. Sometimes, of course, an
overview needs several paragraphs rather than one sentence. In a
user's manual, I'd also add a bulleted list of all the times when
you need the Job View window. This is so much more useful than
being told what the heading just told you. And it's worded so
that even if you skip the heading, the sentence still introduces
you to the following content.

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author, _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597/002-3618777-1904817
http://www.manning.com/Kovitz


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



Previous by Author: The Black Art of Estimation
Next by Author: Re: Metadiscourse
Previous by Thread: Re: Productivity Metrics: MS Word vs Structured Authoring (longish ramble)
Next by Thread: Re: Metadiscourse


What this post helpful? Share it with friends and colleagues:


Sponsored Ads