Friday, November 17, 2006

[Warning: Taking any of the advice in today's blog could prevent you from winning awards in publication competitions.]

Metadiscourse is talking about the talking or writing about the writing. For example, the beginning of this sentence is metadiscourse; it has no content but tells you that what follows is an example. Metadiscourse can be a useful device to help listeners and readers know how to process what is about to come. Which, as an aside, has always made me doubt the effectiveness of putting them at the end of the discourse, as in this sentence for example.

Metadiscourse exists at the document level as well. For example, a table of contents is a form of metadiscourse.

I sometimes find myself having to wade through layers of metadiscourse to get to the value of a document. This seems most inconvenient when I am trying to navigate a PDF manual using the bookmarks. It seems like it takes me way too many clicks to get to where I find anything of value.
Ah, the chapter on Painting Widgets, just what I need. Let me click on Introduction:
"Introduction: This chapter is about how to paint widgets."
Hmmm. OK. Let me click on Overview.
"Overview: This chapter has the following topics:
  • All About Widgets
  • All About Paint
  • Procedures"

I'll just click on Procedures:

"This section describes the following procedures:

  • Selecting a color
  • Preparing the widget
  • Painting the widget"

Let's just go to Painting the Widget

"Follow this procedure to paint a widget"


We need to get readers to the good stuff quicker. How?

Don't make the TOC (or bookmarks in a PDF) overly detailed. Maybe just a listing of the chapters is all that is needed. An information-mapped document probably only needs chapter titles and map titles. Listing every block label in the bookmarks or TOC is probably excessive.

Stop writing chapters called "About this Guide" where we tell the reader why we italicize some words, do some in courier, some in bold, etc. I don't think the following scenario happens:

Hmmm here's a definition and the word browser is in italics. Let me go to Chapter One and see what's up with that. Oh, apparently browser is the term being defined. Glad I looked up the Conventions Used in this Guide piece.

And let's avoid Intros that restate the Topic title in sentence formats, or stem sentences that restate topic headings, etc. Let's rethink if every chapter needs a local TOC (or not call it Overview in the Bookmarks).

It's not that I don't know about nor value advanced organizers. But they're kind of like speed bumps; they're good too, but too many in short succession make me put the Wrangler in 4-wheel drive and take to the sidewalk.

End of Rant

No comments: