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.
There are some documents that need explanation, like timetables.
There are also some documents, like textbooks, where there are multiple
audiences and, for some of them (teachers, some parents) at least some of
the time, the subject matter is the textbook, not what the textbook covers.
For a teacher, the "this chapter describes the influence of the ink color
choices of Confederate generals on the price of Oolong tea in the London
market" bit is quite helpful when designing a lesson plan, or for the
interested parent who wonders what Timmy is studying tonight.
Metadiscourse can be used to mirror the "tell them what you are going to
say, say it, tell them what you said" structure that works so well in spoken
communication. For materials that are designed to support a presentation,
Metadiscourse may be very appropriate.
But for most technical communication, Metadiscourse is either redundant or a
symptom of poor design. If you have to explain how to use the manual, there
had better be a damn good reason why you didn't make it simpler. Under the
usual circumstances, a substantial part of your audience isn't going to read
the Metadiscourse, and the information will be lost.
mike -dot- huber -at- software -dot- rockwell -dot- com
nax -at- execpc -dot- com
> 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.