An argument for metatext

[Tim Altom <taltom -at- SIMPLYWRITTEN -dot- COM>]

I have to take some exception to Ben Kovitz's criticism of the following as
being unnecessary "metatext". I, too, have dealt with government agencies
that spent much of their ink and toner forming trapdoors. But I'd argue that
a good introduction, while perhaps being called "metatext" for convenience,
isn't so much windup as a good signpost.

>Metatext:
>
>    2.1 The Job View Window
>
>    This section describes the Job View window.

Often in documentation we run into multiple tasks that are confusingly
similar: "Print from the network" and "Print from the network server" for
example. In the Clustar Method, we advocate putting a short Introduction
Element of a sentence or two right up-front, sentences that don't merely
reproduce the heading, but reinforce the heading, giving the user a bit
bigger address sign. Remember that many users are tentative when they use a
manual, because they're venturing into unfamiliar territory. A bit bigger
signpost is often worth a few seconds of potential confusion to the user.

Note, too, that with the Clustar Method, we would never, ever, use a heading
like "The Job View Window", because the Clustar Method emphasizes task
breakdown, not system breakdown. Ben is right in his example, I think,
because in his example the heading and introduction are almost identical.
But if we were to recast it a bit into a task orientation, the purpose of
the introduction element becomes clearer:

  2.1 Entering a New Job
        Use these steps to enter a new job from initial data. To scan for
incomplete existing jobs, see...

In this case, I don't think the same objection to metatext applies. And
notice too that we've now incorporated the intent of Ben's revised content,
as shown below:

>
>Introductory content:
>
>    2.1 The Job View Window
>
>    The Job View window displays and lets you edit all information
>    pertaining to a job.

We'd argue, though, that it's best to just shift to a task paradigm, rather
than mingling it with a system orientation of "this window, that window...".
Users are task-performing creatures, not system appendages. They use window
names only as occasional roadside markers, not as central characters in the
drama they play out every day.

Tim Altom
Adobe Certified Expert, Acrobat
Simply Written, Inc.
The FrameMaker support people
Creators of the Clustar Method for task-based documentation
317.899.5882
http://www.simplywritten.com


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