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.
Definitely. Tufte gives an example of a really wild timetable where the
slope of the line indicates the speed of the train. Not sure what use that
is, but it's neat, and it probably requires explanation. And of course I'm
not objecting to things like headings on tables and legends on graphics.
Of course, it still pays to stop a moment and think if there's a way to
draw the graphic in such a way that it's self-explanatory. 90% of the time
there isn't, but there's that other 10%.
>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.
Interesting point! One of the neatest examples of useful metatext I've
come across is in _Prelude to Mathematics_, by W.W. Sawyer. In the
introduction, he has a graphic in which each chapter is depicted as a box.
Some of the chapters are piled on top of other chapters, to indicate that
you have to read the lower chapters in order to understand the chapters
that are piled on top of them. So this shows you that some chapters are
independent and can be read in any order, but others have to be read in a
certain sequence. Graphics (or text) like this is essentially an
instruction manual for operating the document (like your example of a
documentation database).
>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.
Wow, another excellent point. Can't believe I forgot this. Not only do
many people ignore metatext, especially if it's far away from the text that
it describes, but useless metatext drives people away from the document,
sometimes just by increasing its bulk. And I have to say, while I thought
that graphic in the W.W. Sawyer book was neat, I never looked at it a
second time. I just skimmed around randomly the way I normally do. It's
really pretty lucky that I even bothered to look at the introduction, and
there would have been no harm if I hadn't.
(Ah, but the graphic served an ulterior purpose, pertaining to the subject
matter. The graphic itself teaches the mathematical way of thinking that
the book is about.)
--
Ben Kovitz <apteryx -at- chisp -dot- net>
Boulder, Colorado
