TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
