writing & editing

The

Concept, Task, and Reference

Are the Keys to Quality—
Whether or Not You Use DITA
10 intercom SeptembeT/October 2008

i

HINk| emember the television
• commercial where the
WHjk kid. the mom, or the
• dad would snatch and
mm B i t h e n dearly hold onto
I
the Eggo waffle the second it
popped up from the toaster?
If you think waffles are hard to
let go of, try convincing tech-
nical communicators that the
content they create belongs to
the community in a variety of
media.
September/October 2008
The explosion of content manage-
m e n t systems (CMSs), a u t h o r i n g tools,
and a variety of applications for devel-
oping, reviewing, and publishing i n -
f o r m a t i o n begs these questions of new
and seasoned technical communicators:
What should be o u r focus? Should we
concentrate on w h i c h CMS to purchase?
H o w m u c h money should we spend and
how do we select a vendor? Should we
throw the same o l d content we've had
for years i n t o a w i k i and hope for the
best? In w h i c h tools should we invest
our time and resources?
All About Content
O u r focus s h o u l d be what it always
s h o u l d have been—the c o n t e n t itself.
T h e toaster isn't a bad metaphor, be-
cause we a l l want the i n f o r m a t i o n
we want w h e n we want i t . We want to
search f o r s o m e t h i n g e x p l i c i t l y or gen-
erally and have the r i g h t i n f o r m a t i o n
p o p up to greet us. We want to get it
w h i l e it's h o t i n o u r m i n d s — n o t too
m u c h a n d n o t too l i t t l e , b u t j u s t r i g h t .
G o o d technical w r i t i n g is i n t e g r a t i n g
i n f o r m a t i o n i n t o logical chunks that
act as b u i l d i n g blocks for larger frames
o f reference. Let's p u t o u r t i m e a n d
t h o u g h t i n t o the ingredients o f the
bread a n d w o r r y later about w h i c h
b r a n d of toaster to buy. T h e most ex-
pensive toaster w i l l never i m p r o v e the
quality of the bread itself.
It matters how we write and it matters
how well we write. In the w o r l d we live
in today, technical c o m m u n i c a t i o n , like
the Web, belongs to everyone. Content
never has truly been "owned" by techni-
cal writers, b u t now there is less camou-
flage to shadow that t r u t h . For the most
part, the role of technical writer has
always been liaison between engineers
and users, even when the users are engi-
neers. N o w that googleis a verb and many
users are at least as computer savvy as
we technical communicators m i g h t be,
fewer and fewer people are impressed
by nice f o r m a t t i n g and book covers.
We've k n o w n for years that most
people d o n ' t use the table of contents
i n o u r books o r o n l i n e help, b u t y o u
can still f i n d tons of PDFs that are nei-
ther i n d e x e d n o r composed in a way
that makes locating i n f o r m a t i o n easy.
intercom
writing & editing
Most PDFs I see d o n ' t even have auto-
generated bookmarks, m u c h less an
index, a n d this always makes me won-
der what the author was t h i n k i n g w h e n
the material was published. D i d y o u
want me to f i n d the i n f o r m a t i o n I ' m
l o o k i n g for or d i d y o u want me to read
your m a n u a l as t h o u g h it were a Dean
Koontz novel?
Perhaps, sometimes, the matter is
precisely that we aren't t h i n k i n g when
we publish the variety of materials we
expect users to use. We get so caught up
in spelling o u t acronyms, consistently
labeling figures, or using serial commas
per style guide specifications that we for-
get the more i m p o r t a n t facets of a docu-
m e n t in its users' eyes. H o w easy is it to
navigate to f i n d information? A n d , for
the purpose of this article, how easy is it
to digest the i n f o r m a t i o n when you've
f o u n d it?
A t o o l is only a vehicle, albeit a very
i m p o r t a n t part of the process. W i t h o u t
eighteen-wheelers and other means, we
w o u l d n ' t have as many choices in the
grocery store as we do today. The future
w i l l b r i n g new fuels and new vehicles,
but w e ' l l still need to get stuff f r o m there
to here, f r o m here to there. Tools are
only as useful as the stuff they transport.
A n d no matter how great your w i k i or
your CMS o r your X M L editor o r your
PDF reader or your D I T A or other ar-
chitecture or for that matter your pencil
or pen, it's the content that really mat-
ters. I n f o r m a t i o n mapping, Total Qual-
ity Management, Minimalist W r i t i n g ,
and 1+1 aren't new concepts; they are
j u s t methods to handle the process by
w h i c h people discover, assess, wrangle,
and communicate i n f o r m a t i o n .
Design Is Function
The freer information becomes, the
more basic structure it requires to retain
integrity: Design is function. Approach-
i n g modular content f r o m a structured
w r i t i n g perspective logically breaks the
content down i n t o topic types that can
be explained by the D I T A terms concept,
reference, and task. O u r focus should be on
how we can parse information into logi-
cal pieces or topics, w i t h the simple goal
of describing what, why, and how, and
providing specifications of parameters,
11
writing & editing
options, and other technical details. You
can p u t the pieces together in various
ways to b u i l d various types of documents,
much like you can b u i l d a dinosaur, a
bridge, or a spaceship w i t h Lego blocks.
Concept Topics
W h e n we set o u t to write about an
idea, we should concentrate on its rele-
vance to the user. Before w r i t i n g about a
concept, t h i n k about the bigger picture.
W h o is the audience? W h a t will the us-
ers do w i t h this information? What is i m -
portant to explain in order to facilitate
understanding about tasks various users
m i g h t want to or need to perform?
W r i t i n g about a concept requires
p r o v i d i n g an overview of why and what
a t h i n g is (a software feature, for exam-
p l e ) . Some users want a b r i e f overview
and others want a deeper understand-
i n g . A best practice for w r i t i n g a concept
topic is to start w i t h a concise d e f i n i t i o n
that m i g h t be used in a glossary and t h e n
give m o r e in-depth i n f o r m a t i o n so read-
ers grasp the framework w i t h i n w h i c h
their use of a f u n c t i o n makes sense. A
concept illustrated by a graphic a n d / o r
an example has the best chance for suc-
cess, because the content is designed to
speak to a variety of readers—those w h o
are m o r e visually stimulated, those w h o
need the tangible effects only real-life
scenarios can give, and those w h o j u s t
need the tightly written glossary defini-
t i o n that presents the i n f o r m a t i o n in a
nutshell.
Task Topics
N o w that I understand the purpose of
a software feature, how do I use it? Tech-
nical communicators are best k n o w n
for w r i t i n g procedures, so when we hear
about parsing content i n t o a task topic,
we feel we've been d o i n g that successful-
ly for years. A n d perhaps we have. Those
of us w h o have conducted usability test-
ing, whether official (using a lab, paying
thousands o f dollars to get certified, fol-
lowing precise procedures) or unofficial
(having various folks outside the team
o r department r u n t h r o u g h procedures
to f i n d p r o b l e m spots or errors), m i g h t
already have some insight i n t o how we
can continue to improve the instruc-
tions we write.
12
Regardless of our experience, we that must be met before a task can be
can focus on our approach and t h i n k p e r f o r m e d are easier to understand
t h r o u g h ways to make it better. For i n - when spelled o u t as prerequisites or list-
stance, I have analyzed content in what ed as the first steps of the procedure.
m i g h t have been considered concept W r i t i n g a task topic involves j u s t a few
topics ("planning" this and "determin- simple guidelines. Focus on any prereq-
i n g " that) and f o u n d that some of the i n - uisites necessary to do something, be spe-
f o r m a t i o n worked m u c h better as steps cific about what that something is, and be
in a procedure. Often the procedure clear about how to do it. It's i m p o r t a n t
already existed and was m u c h i m p r o v e d to provide a context that makes clear the
by adding the couple of steps, and re- need to p e r f o r m the task. If reusing part
m o v i n g those steps f r o m the concept i n - of a concept topic (or glossary term and
f o r m a t i o n made the latter m u c h m o r e definition) is helpful to the user, include
concise and digestible. Requirements it in the i n t r o d u c t i o n to the steps.
!:A fort
To reach your team's
potential for efficiency
a n d productivity, every-
one must be involved.
For reuse to be a reality,
each writer a n d editor,
for example, should fol-
low structured w r i t i n g
guidelines and develop
topics that can stand
alone as well as be used
as b u i l d i n g blocks w i t h
other topics. Following
are some best practices
for approaching m o d u -
larity f r o m a structured
w r i t i n g perspective:
Engage
Involve the team: Every team member's participation is valued.
Invite discussion: Each person has a say in developing the process.
Interact regularly: Get together as a team to check progress and discuss.
Elicit
H o l d regular meetings: Make it a p o i n t to learn together h o w to improve the
process.
Use real examples: W o r k together to improve real content for a real product.
Be a role m o d e l : "Write u n t o others as y o u ' d like t h e m to write u n t o you." This
spin o n the golden rale will make content easier to share/reuse.
Exhibit
Deliver products on schedule: F o l d structured w r i t i n g i n t o your process while
c o n t i n u i n g to meet the usual p r o d u c t deadlines; w o r k o u t your process as a team.
F o r m a prototype sub-team: Have a few team members w o r k on prototypes to
share.
Promote modularity t h r o u g h editing: Foster structured w r i t i n g by p o i n t i n g o u t
content types and gaps t h r o u g h the e d i t i n g process.
intercom September/October 2008

Reference Topics
T h e topic type we seem to have the
most trouble understanding is in a way
the most i m p o r t a n t for technical com-
municators to i m p l e m e n t , because it
is often the most substantive and the
least intuitive. The really g o o d stuff—
technical details, parameters, compari-
sons that tell users why they should use
this feature over that one—is often the
i n f o r m a t i o n in a reference topic. Refer-
ence content is often displayed in table
format, b u t it doesn't have to be.
In workshops where writers learn
to label content w i t h the basic three
types, people always have problems u n -
derstanding the differences between
concept and reference i n f o r m a t i o n .
One reason is that they look the same,
whereas task content almost always has
n u m b e r e d steps. A n o t h e r reason is that
the content m i g h t not be written well in
the first place. W h e n different types of
i n f o r m a t i o n are intertwined, writers and
editors have trouble analyzing it and
readers have trouble understanding it.
The three basic types of i n f o r m a t i o n
can be explained this way: a concept
topic describes why and what, a task top-
ic describes how, and a reference topic
provides the details necessary to make
i m p o r t a n t decisions, often involving
when and where—for example, when to
p e r f o r m a task, configuration informa-
t i o n (settings, options) to keep in m i n d ,
and technical details, specifications, or
parameters to consider.
Quality through Process
G o o d w r i t i n g looks effortless; howev-
er, as we all know, it is h a r d work. W h e n
we approach o u r w r i t i n g in the same
way other parts of o u r businesses ap-
proach their functions (marketing, soft-
ware and hardware development, oper-
ations, support), we provide solutions to
o u r customers. In the case of technical
communicators, some of our best w o r k
happens w h e n we write to prevent prob-
lems, and using the logic of structured
w r i t i n g we can accomplish this. T h i n k
about it. Does your team find it needs
more and more troubleshooting docu-
mentation? W h a t can you do to b u i l d
quality i n t o your w r i t i n g process that
will result i n more satisfied customers?
September/October 2008
Some of our best
work happens
when we write to
T h i n k i n g in terms of concept, refer-
ence, and task is guaranteed to improve
the quality of your content, regardless
o f the tools you have o n hand. You will
use fewer words, w h i c h results in savings
for your customers (who will spend less
time reading) and for your company
(which will spend less money o n transla-
tion) . The content will have more d e p t h
because i t will be richer, more concise,
and more coherent.
W h e n y o u first attempt to parse i n -
f o r m a t i o n i n t o the three topic types—
especially when revising legacy content
to be more m o d u l a r — y o u ' l l come across
i n f o r m a t i o n thatjust doesn't seem to fit.
But as you t h i n k it t h r o u g h , the camou-
flage o f wordiness will disappear, y o u ' l l
tease o u t the separate threads of m i x e d
i n f o r m a t i o n types, and y o u ' l l find that
most i n f o r m a t i o n can be classified as
concept, task, or reference. Gaps in log-
ic will reveal themselves; content that
seemed sufficient will clearly need more
attention if users are to have the best
chance o f getting what they need. Fill-
i n g in these gaps is one way of prevent-
i n g problems for your customers.
It is best practice to focus on the three
content types and discuss as a team how
to handle what appear to be exceptions.
I n some cases, brainstorming with fellow
team members m i g h t help you see the
i n f o r m a t i o n in a fresh way. Sometimes,
you m i g h t determine as a team that you
intercom
writing & editing
need a f o u r t h or fifth type. I n such cases
you should consult w i t h an i n f o r m a t i o n
architect or do some research on the
current t h i n k i n g o f the D I T A experts
(regardless of whether y o u are using
D I T A ) to learn about the logic of, say,
a troubleshooting topic type. The most
i m p o r t a n t t h i n g is for everyone on your
team to approach the w r i t i n g process
f r o m the same logical perspective. (For
suggestions on how your team can best
approach structured w r i t i n g , see the
sidebar on page 12.)
The Future Will Be DITA-like
Remember in the late 1980s and early
1990s when "email" was far f r o m being
a household w o r d , STC d i d n ' t have a
website, and there was no such t h i n g as
an I n t e r n e t Service Provider? Leaders
in academia said the future m i g h t n o t
totally be U N I X , but it w o u l d be U N I X -
like—that is, the future w o u l d be open
and the c o m m u n i t y m i g h t be as b i g as
the w o r l d itself. Similarly, the future of
technical c o m m u n i c a t i o n m i g h t n o t be
D I T A , but it w i l l probably be DITA-like,
because the freer i n f o r m a t i o n becomes,
the more logically we must approach it
so that it has an order and a structure in
w h i c h it makes sense, regardless of how
it is navigated.
W h e t h e r your operating system is
U N I X is irrelevant, because the Internet
is b u i l t on the idea of openness. You can
use anything to get to it. A n d even if y o u
d o n ' t t h i n k you understand D I T A o r
CMS or this or that other t o o l or medi-
u m , i t doesn't matter when y o u write i n
such a way that your customers get the
i n f o r m a t i o n they need. B u i l d i n g quality
i n t o your processes can help your team
reuse content and save time and money
by being more efficient and productive.
Tools come and go, b u t good w r i t i n g
b u i l t on g o o d logic is always in style. ©
A professional technical communicator for
about twenty years and senior member in the
Atlanta chapter, Debbie (lmnop@mindspring
.com) has been active in STC as a presenter,
judge, and award-winner. She has worked as
principal writer, multimedia specialist, direc-
tor, manager, and trainer and is currently
most happy in her role as information archi-
tect at Sun Microsystems.
13
 | THE MAGAZINE OF THE SOCIETY FOR TECHNICAL COMMUNICATION

September/October 2 0 0 8
THE MAGIC THREE
STC'S STRATEGIC PLAN
STC COMPETITIONS:
BEST OF SHOW

When
Good
Projects
Learn to
Address
Problems
As Soon As
They Arise
iiliiliiditiliiiiiiilttliiiilimilllimiilitiilmillliliil

1129*8 i urn
M B S . P A U L A M KAPJLOW P377
BECKMAN COULTER, INC 114 539
74 51 IK'INTON DR.
INDIANAPOLIS I N 4626S-51G3