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.
George Grider, thanking techwr-l for providing suggestions about good
demonstration topics, observes: <<There are inherent difficulties in using
[the demonstrations we suggested]... procedures requiring complex wordings
(such as tying a shoe or building a paper plane) require pictures, not
words. This is supposed to be a writing exercise. Second, with the kind of
familiar processes easily tested at a conference table (such as installing a
paper clip or making a sandwich), the readers' familiarity with the process
gets in the way of their reliance on a readable and accurate document.>>
Actually, both observations are one of the strengths of such an example. In
the first case, even a really bad sketch would suffice to show where a
picture could replace 1000 words, and that's an important thing to consider
during revisions. And as for the second case, "familiarity breeds contempt",
and you never want to be seen as contemptuous of your readers. So part of
the documentation process (whether audience analysis and the development of
specifications or usability testing and proving the specs were correct) must
be a means of discovering whether graphics are a better solution than words,
and getting past your familiarity with a product so you can think like its
users.
<<The exercise I'm looking for is one which will demonstrate the importance
of making revisions. No matter how well you write it the first time, there's
going to be flaws.>>
The typical flaws in a documentation project arise from a variety of common
problems: stylistic problems (e.g., one person calls it a window, the other
calls it a dialog box), accounting for changes in the product that don't get
communicated to the writers ("what do you mean it now only runs under
Windows NT?"), assuming readers know more than they do (e.g., unplugging the
toaster before sticking a screwdriver in it to remove the toast), and making
a change in one place that affects text somewhere else (and potentially
throughout the document). There are other categories, and hopefully techwr-l
can help you develop a complete list. The trick in designing a good exercise
is to pick something simple and familiar (your choice; you had a lot of
suggestions) and creating a few traps for the writers who will revise the
document. One trap per error type I've just listed will suffice, but two
would be better.
Consider the sandwich example to illustrate this principle (and you can
certainly pick a better example for the real exercise): Style problems could
include whether we refer to jam or jelly, and although only a purist would
require us to distinguish between the two, there may be cases where the
distinction is important. They could also consider whether "spread" or
"apply" is the best word for the process of peanutbuttering. Product changes
might include a switch in the spec from white bread to whole wheat or to
rye, and whether the peanut butter is refrigerated or at room temperature
(which determines whether you'll tear the bread when you spread the stuff).
False assumptions might be that your students are writing for you, when in
fact the audience is 8-year-olds, or that the audience has a special-purpose
peanut butter spreader, when in fact they only have butter knives. And
making a change in one place that ripples throughout the document might
involve changing the spreadables from peanut butter to Velveeta, The Cheese
That Never Dies (TM); it's obvious to change "peanut butter" to "Velveeta"
everywhere, but considerably less obvious that you'll probably not want to
include grape jelly on the sandwich anymore.
<<And unless you're working for a Sony or Microsoft, there's going to be
mistakes.>>
Right. Because Betamax was intended solely as a stimulant to VHS research,
and Microsoft doesn't make mistakes, they just incorporate unreliable
features that you didn't know you needed. <gdrlh>
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
