<html>
<head>
<title>STC Article</title>
<META NAME="Keywords" CONTENT="technical writer, writer, documentation, online help, on-line help, editorial, publications, NeXT, NeXT Computer,Casabona">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style>
body {
margin:40px 10px 40px 40px;
padding:0;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 80%;
}
#left {
width:600px;}
#leftMargin {
margin-left:219px;
background: url(images/articles/background_content.jpg) repeat-y left;}
#subhead {
font-size: 120%;
font-weight: bold;
}
#head {
font-size: 130%;
font-weight: bold;
}
#rule {
font-size: 80%;
margin-bottom: 0px;
padding-bottom: 0px;
}
#caption {
font-size: 80%;
}
</style>
</head>
<body bgcolor="#FFFFFF" text="#000000" leftmargin="0" topmargin="0" marginwidth="0" marginheight="0" onLoad="MM_preloadImages('file:///C|/Documents%20and%20Settings/Helen/My%20Documents/Casabona/CasabonaRoot/Images/PortfolioNavBar_r1_c2_f2.gif','file:///C|/Documents%20and%20Settings/Helen/My%20Documents/Casabona/CasabonaRoot/Images/PortfolioNavBar_r3_c2_f2.gif','file:///C|/Documents%20and%20Settings/Helen/My%20Documents/Casabona/CasabonaRoot/Images/PortfolioNavBar_r5_c2_f2.gif','file:///C|/Documents%20and%20Settings/Helen/My%20Documents/Casabona/CasabonaRoot/Images/PortfolioNavBar_r7_c2_f2.gif','file:///C|/Documents%20and%20Settings/Helen/My%20Documents/Casabona/CasabonaRoot/Images/FooterPortfolioBody_r2_c2_f2.gif')" link="#000099" vlink="#0000FF" alink="#990099">
<div id="left">
<P id="head">The Finer Points of Writing User Documentation</P>
By Helen Casabona
<p>(The
following article was originally published in the 1995 Society of Technical
Communication conference proceedings.)</p>
<p>When
I was in the user publications group at NeXT, we were handed a charter
to create casual books with personality. We were also told to condense
the user documentation for an entire operating system and several bundled
applications into 300 pages. And of course we had the top priority of
providing accurate, complete, and easy-to-use information. The keys to
pulling this off? Task orientation, flat hierarchy, carefully crafted
page design, illustrations, and a casual, intelligent tone. We also broke
some "rules"!</p>
<p id="rule">Organization<hr size="1" noshade></p>
Simple, task-based user's guides are all the rage these days—or at
least they should be. When documenting a piece of software, you've got
to pull out all the stops to make it easy for your readers to learn exactly
what they want to know. This means dispelling a few myths. Namely, you
don't have to organize your book around the user interface, you don't
need multiple level headings, and you can and should make topics fit on
one page or two facing pages. The result can be a book that looks and
works great.</p>
<p id="subhead">Document Tasks, Not the Interface</p>
<p>When you document software that people perform tasks with, focus on the
tasks, not on parts of the interface. Instead of a topic "Using the
Font Panel" that explains settings in a panel (panel is NeXT's term
for dialog box), document what you do with the panel, as in "Setting
a New Font."</p>
<table width="400" border="0" cellspacing="3" cellpadding="0">
<tr>
<td id="caption" width="181">Don't
make readers infer what to do from how things work.</td>
<td id="caption" width="210">Tell
them what to do and they <br>
will see how things work.</td>
</tr>
<tr>
<td colspan="2"><img src="http://www.casabona.com/images/STCPaper/FontPanel.gif" width=357 height=236 border=0 alt="Example" align="top"></td>
</tr>
</table>
<p>You may find that a window
or panel requires several tasks—for example, "Setting a Font"
and "Previewing a Font." Depending on how your document and
the interface are organized, these various tasks might even go in different
parts of the book. That's OK. Organize tasks to make sense to the reader
first, and secondarily to match the interface.
<p id="subhead">Think Sequence, Not Hierarchy</p>
<p> Readers can get lost in second-, third-, and fourth-level headings—especially
when the headings fall on different page spreads and aren't distinct visually.
That's why in the <i>NEXTSTEP User's Guide</i>, we did away with such
hierarchy. Instead, each chapter consists only of top-level tasks.
<p>In many cases, you can eliminate
subtopics simply by elevating them to the top. Instead of relating the
topics hierarchically, consider the best order to present them in. If
there are several ways to do the same thing, begin with the most common
way and then follow with variations—for example, "Opening a Folder"
and then "Opening a Folder by Typing." Ask yourself these questions:
Is there a chronology, as in "Starting up the Edit Application,"
"Creating a New Document," and "Saving a Document"?
Is there a progression from basic to advanced, as in "Looking Up
Mail Addresses," "Creating a Mail Address Book," and "Creating
Your Own Group Address"? Or is there just a list of separate but
related tasks?
<p id="subhead">Fit Topics on One- or Two-Page Spreads
<p>You can do readers an incredible service by fitting topics on either one
page or two facing pages. Try even to have single-page topics on facing
pages complement each other. For example, "Typing Text" might
face "Selecting Text." Readers can then see the entire scope
of a topic at a glance.</p>
<table width=400 cellspacing=3 cellpadding=0 border=0>
<tr>
<td id="caption" width="195" valign=top height="30"> Each
topic should occupy <br>
either one or two pages.</td>
<td id="caption" width="198" valign=top>Two-page
topics should occupy the same split.</td>
</tr>
<tr valign="top">
<td colspan=2 height="132"><img src="http://www.casabona.com/images/STCPaper/PageSpread1.gif" width=397 height=107 border=0 alt="Example">
</td>
</tr>
</table>
<table width=400 cellspacing=0 cellpadding=0 border=0>
<tr>
<td id="caption" width="398" valign=top>Don't
make the reader turn pages within a topic. </td>
</tr>
<tr>
<td valign=top><img src="http://www.casabona.com/images/STCPaper/PageSpread2.gif" width=398 height=107 border=0 alt="Example"></td>
</tr>
</table>
<p>If a task is too involved
to fit on one or two pages, break it up into several tasks. Instead of
tackling "Getting Faxes" all at once, document "Checking
for Faxes," "Opening a Fax," "Changing How a Fax is
Displayed," and so on.
<p>If a task has a too many variations
to fit on a page or spread, describe the vanilla case in one task and
describe each option in subsequent tasks. For instance, the topic "Sending
a Message" can describe sending a no-frills electronic mail message.
"Attaching a File or Folder," "Recording and Inserting
Sound in a Message," "Forwarding a Message," and so on,
elaborate on how to dress the message up.
<p>It takes effort to write to
a page or spread, but that effort results in streamlined and well thought-out
writing. You learn to think carefully about whether certain information
is truly necessary—for instance, must you really point out that clicking
a button highlights it? You also learn to cut extraneous language and
to replace long descriptions with illustrations. Working in a strong page
design with a good editor will do wonders for your writing.
<p id="rule">Page Design<hr size="1" noshade></p>
It's perhaps an unfortunate fact, but most people don't really want to
read user documentation. Instead, they eventually have to. When this happens,
they want to find an answer fast—not just the topic that contains
the answer, but the answer within the topic. This is where a good page
design comes into play.
<p id="subhead">Put Everything in Its Place</p>
<p>You can make specific types of information on the page visually distinct
so readers can key in quickly on what they're looking for. In the <i>NEXTSTEP
User's Guide</i>, how-to steps provide the bare bones "how do I do this,"
body text and illustrations provide context and details, cross-references
are set apart in the lower margin where they don't interrupt the main discussion,
and information that's not immediately part of a task is set apart in a sidebar.
</p>
<p><a href="TaskPage.html"><img src="http://www.casabona.com/images/Thumbnails/TaskPage.gif" width="123" height="159" border="1"></a>
<br>
<a href="TaskPage.html">Click to see a larger view</a></p>
<p>Readers can quickly choose
what they want to focus on. Also, the distilled information comes in shorter,
more manageable chunks.
<p id="subhead">Make Each Element Work on Its Own</p>
<p>A segregated page design works well for all kinds of readers—whether
they look first at steps, at body text, or at illustrations. Just make
sure that each element makes sense when read on its own. How-to steps
should provide just enough information for a reader who doesn't need context
or details. The callouts and illustrations should make sense if they're
all you read. And since cross-references are set apart from the text they
refer to, they need context, too: </p>
<table width="400" cellspacing=0 cellpadding=0 border=0>
<tr>
<td id="caption" width="20%" valign=top><b><i>Example</i></b></td>
<td id="caption" width="80%" valign=top>You
can also set font properties with the Bold or Italic command. See
"Standard Commands." <p>If
you don't know an address, you can look it up. See "Looking
Up Mail Addresses" in Chapter14. </td>
</tr>
</table>
<p id="subhead">Replace Words with Pictures</p>
<p> To document a graphical user interface you have to show pictures of what
you're talking about. Obvious tactics are to illustrate a sequence of
events in a task or to identify parts of the interface. But don't stop
there. Use illustrations in place of wordy explanations. Look through
your documentation for big chunks of text and ask yourself, <i>Could I
show this with an illustration?</i> For example: </p>
<table width="400" cellspacing=3 cellpadding=3 border=0>
<tr>
<td id="caption" width="20%" valign=top><b><i>Instead
of</i></b></td>
<td id="caption" width="80%" valign=top>You
can type a range of pages in the From and To fields. If you type a
starting page number, the To field automatically changes to last and
the file prints from your starting page to the end. If you type an
ending page number, the From field automatically changes to first
and the file prints from the beginning to your ending page.</td>
</tr>
<tr>
<td id="caption" width="20%" valign=top><b><i>Try
this</i></b></td>
<td id="caption" width="80%" valign=top>You
can type a range of pages:</td>
</tr>
</table>
<table width="400" cellspacing=3 cellpadding=3 border=0>
<tr>
<td width=283 valign=top> <img src="http://www.casabona.com/images/STCPaper/PrintPagesCallout.jpg" width=280 height=130 border=0 alt="fields in the Print panel"></td>
<td id="caption" width=* valign=top>These
fields are filled in automatically if you type only one page number.</td>
</tr>
</table>
<p id="subhead">Just Say It Once
<p> It's tempting to repeat information in a callout that's also stated in
a how-to step or body text. If a step says <i>Click in the window to bring
it forward</i>, a callout pointing to an illustration of the window can
say the same thing, right?
<p>The fact is, in a page-oriented
design you can't waste page real-estate by repeating information. If you
must reiterate something, try to add another piece of information or perspective.
If a how-to step says <i>Click in the window to bring it forward</i>,
the callout can say <i>Clicking in a window makes it the active window</i>
or <i>When a window comes forward, its title bar becomes black</i>.
<p id="subhead">Use Sidebars to Keep Tasks Streamlined</p>
<p>Even in a task-oriented document you have to explain concepts. You may
also have tables of data or a lengthy list of options. To keep tasks streamlined,
try putting information that isn't immediately part of a task in a sidebar
or feature page. This information can include concepts, options, overviews,
extended descriptions, tables, and so on. </p>
<table width=330 cellspacing=4 cellpadding=4 border=0>
<tr>
<td id="caption" width="50%" valign=top>A visually distinct sidebar on the same page
as a task provides information peripheral to that task.</td>
<td id="caption" width="50%" valign=top>A feature page can contain peripheral information
that isn't subordinate to one task but relates to many.</td>
</tr>
<tr>
<td colspan=2 valign=top><img src="http://www.casabona.com/images/STCPaper/SidebarSpread.jpg" width=330 height=207 border=0 alt="sidebar example"></td>
</tr>
</table>
<p>Readers aren't interrupted
with peripheral information while trying to perform a task. Instead, they
can read it at their convenience. To help them know whether the sidebar
or feature page contains information they need, use a descriptive heading
rather than a label. Instead of "Fonts" try "What Is a
Font?"</p>
<p id="rule">Style<hr size="1" noshade></p>
Gone are the days of being told not to use the second person you. Also
on the wane is our profession's obsession with the passive voice. That's
a relief! But to really connect with readers, try relaxing your style
even more.
<p id="subhead">Write Like You Speak
<p>Write the way you would talk to a reader you know, like, and respect.
Use contractions when natural. For example, <i>Don't delete the file</i>
reads a lot more smoothly than <i>Do not delete the file</i>.
<p>Go ahead and end a sentence
or phrase with a preposition if that's what sounds most natural. For example,
people read <i>the folder you're copying from</i> more easily than <i>the
folder from which you are copying</i>. Also, avoid academic writing, even
if it means breaking a grammatical tradition. For example, <i>There's
no ellipsis in its icon</i> is more accessible to readers than the stilted
<i>No ellipsis is in its icon</i>.
<p id="subhead">But First, <i>Please</i> Tell Me Why I Care</p>
When you introduce a task topic, you can get your readers' attention and
best make your point by focusing on what they can do with the software,
not on what a command or window does. Tell readers first what they can
do and why they'd want to do it. Then tell them how. For example, </p>
<table width="400" cellspacing=3 cellpadding=3 border=0>
<tr>
<td id="caption" width="20%" valign=top><b><i>Instead
of</i></b></td>
<td id="caption" width="80%" valign=top>The
Print command opens the Print panel. This panel has options for selecting
a printer, a range of pages, and the number of copies to print.</td>
</tr>
<tr>
<td id="caption" width="20%" valign=top><b><i>Try
this</i></b></td>
<td id="caption" width="80%" valign=top>When
you're ready to print a file, you select a printer, the pages you
want to print, and the number of copies. You make these choices with
the Print panel.</td>
</tr>
</table>
<p>If you're introducing a concept,
tell readers how the concept relates to them. Under the heading The File
System:
<p></p>
<table width="400" cellspacing=3 cellpadding=3 border=0>
<tr>
<td id="caption" width="20%" valign=top><b><i>Instead
of</i></b></td>
<td id="caption" width="80%" valign=top>The
file system is divided into files and folders. Files contain information
such as documents, and folders contain other files.</td>
</tr>
<tr>
<td id="caption" width="20%" valign=top><b><i>Try
this</i></b></td>
<td id="caption" width="80%" valign=top>Your
computer keeps information in files and folders. A file might be an
article you write or an illustration. A folder can contain other files.
The files and folders make up the computer's file system.</td>
</tr>
</table>
<p id="subhead">Treat Readers As Equals</p>
<p>No matter how inexperienced readers may be with your topic, address them
as intelligent adults. Don't talk down to them or be negative as you might
to a child. For example, instead of <i>You must type your user name exactly
or else you won't be logged in</i>, try <i>If you make a mistake typing
your user name, just try again</i>.
<p>Don't overuse the imperative.
To much <i>do this</i> or <i>do that</i> can be unfriendly and condescending,
especially when the reader has a choice. For example, instead of <i>Press
Return to log out or click Cancel if you change your mind</i>, try <i>You
can press Return to log out, or if you change your mind, click Cancel</i>.
<p>Also, avoid using <i>lets you</i> or <i>allows you to</i>. The computer shouldn't let, allow, or
enable people to do anything. Neither do any of its subparts, such as
commands, menus, or panels. Instead, try <i>you can do xyz</i>.
<p id="subhead">Avoid Techy Words</p>
<p>When you're writing user documentation, there are several technical terms
you can easily avoid. Even though these words may be common in computer
literature, they aren't helpful to the general population. For example,
for many of us it sounds funny to <i>boot our computer</i> or to be a
<i>user</i>. Instead of <i>booting the computer</i> try <i>turning on
the computer</i> or <i>starting the computer</i>. Instead of <i>other
users on the network</i> try <i>other people on the network</i>.
<p id="subhead">Say More with Less</p>
<p> Don't overexplain things. People learn faster when they have less verbiage
to wade through. Provide a concept and just enough information so the
reader can figure out the rest.
<p>For example, don't explain
the result of an action when that result is obvious or irrelevant, such
as that a button is highlighted when you click it or that the screen is
blue when you first turn on the computer.
<p>There's almost always a way
to shorten something after you first write it. For example: </p>
<table width="400" cellspacing=3 cellpadding=3 border=0>
<tr>
<td id="caption" width="20%" valign=top><b><i>Instead
of</i></b></td>
<td id="caption" width="80%" valign=top>How
the Scale button affects your printed pages depends on the application
you're working in.</td>
</tr>
<tr>
<td id="caption" width="20%" valign=top><b><i>Try
this</i></b></td>
<td id="caption" width="80%" valign=top>The
Scale button works differently in different applications.</td>
</tr>
</table>
<p id="rule">Think On a Higher Level<hr size="1" noshade></p>
You can try these ideas in your writing and hopefully see some good results.
Even if you don't agree with everything I've said here, your take-home
message should be to think on a level higher than just getting the facts
and grammar right. Provide solutions for your readers and remember that
whether they're consumers or programmers, they're people just like you.
Give your writing extra thought, from the organization down to the use
(or nonuse!) of each word. Your result can have all the right information
and be short and simple. When your manager says <i>What took you so long?
I could have done this in half the time</i>, you'll know you succeeded.
<p id="rule">References<hr size="1" noshade></p>
(1) Casabona, Helen, Kathi Vian, and Roy West.<br>
<i>NEXTSTEP User's Guide</i>, NeXT Computer, Inc. Redwood City, CA. 1994.<br>
(2) Casabona, Helen. <i>Writer's Handbook for Style and Design</i>, NeXT
Computer, Inc. 1994.
<p>
</div>
</body>
</html>