Sunteți pe pagina 1din 5

writing & editing

The

Concept, Task, and Reference


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

i
writing & editing

HINk| emember the television The explosion of content manage- Most PDFs I see d o n ' t even have auto-
• commercial where the m e n t systems (CMSs), a u t h o r i n g tools, generated bookmarks, m u c h less an
WHjk kid. the mom, or the and a variety of applications for devel- index, a n d this always makes me won-
oping, reviewing, and publishing i n - der what the author was t h i n k i n g w h e n
• dad would snatch and
f o r m a t i o n begs these questions of new the material was published. D i d y o u
mm B i t h e n dearly hold onto

I
and seasoned technical communicators: want me to f i n d the i n f o r m a t i o n I ' m
the Eggo waffle the second it What should be o u r focus? Should we l o o k i n g for or d i d y o u want me to read
popped up from the toaster? concentrate on w h i c h CMS to purchase? your m a n u a l as t h o u g h it were a Dean
If you think waffles are hard to H o w m u c h money should we spend and Koontz novel?
let go of, try convincing tech- how do we select a vendor? Should we Perhaps, sometimes, the matter is
throw the same o l d content we've had precisely that we aren't t h i n k i n g when
nical communicators that the
for years i n t o a w i k i and hope for the we publish the variety of materials we
content they create belongs to best? In w h i c h tools should we invest expect users to use. We get so caught up
the community in a variety of our time and resources? in spelling o u t acronyms, consistently
media. labeling figures, or using serial commas
All About Content per style guide specifications that we for-
O u r focus s h o u l d be what it always get the more i m p o r t a n t facets of a docu-
s h o u l d have been—the c o n t e n t itself. m e n t in its users' eyes. H o w easy is it to
T h e toaster isn't a bad metaphor, be- navigate to f i n d information? A n d , for
cause we a l l want the i n f o r m a t i o n the purpose of this article, how easy is it
we want w h e n we want i t . We want to to digest the i n f o r m a t i o n when you've
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- f o u n d it?
erally and have the r i g h t i n f o r m a t i o n A t o o l is only a vehicle, albeit a very
p o p up to greet us. We want to get it i m p o r t a n t part of the process. W i t h o u t
w h i l e it's h o t i n o u r m i n d s — n o t too eighteen-wheelers and other means, we
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 . w o u l d n ' t have as many choices in the
G o o d technical w r i t i n g is i n t e g r a t i n g grocery store as we do today. The future
i n f o r m a t i o n i n t o logical chunks that w i l l b r i n g new fuels and new vehicles,
act as b u i l d i n g blocks for larger frames but w e ' l l still need to get stuff f r o m there
o f reference. Let's p u t o u r t i m e a n d to here, f r o m here to there. Tools are
t h o u g h t i n t o the ingredients o f the only as useful as the stuff they transport.
bread a n d w o r r y later about w h i c h A n d no matter how great your w i k i or
b r a n d of toaster to buy. T h e most ex- your CMS o r your X M L editor o r your
pensive toaster w i l l never i m p r o v e the PDF reader or your D I T A or other ar-
quality of the bread itself. chitecture or for that matter your pencil
It matters how we write and it matters or pen, it's the content that really mat-
how well we write. In the w o r l d we live ters. I n f o r m a t i o n mapping, Total Qual-
in today, technical c o m m u n i c a t i o n , like ity Management, Minimalist W r i t i n g ,
the Web, belongs to everyone. Content and 1+1 aren't new concepts; they are
never has truly been "owned" by techni- j u s t methods to handle the process by
cal writers, b u t now there is less camou- w h i c h people discover, assess, wrangle,
flage to shadow that t r u t h . For the most and communicate i n f o r m a t i o n .
part, the role of technical writer has
always been liaison between engineers Design Is Function
and users, even when the users are engi- The freer information becomes, the
neers. N o w that googleis a verb and many more basic structure it requires to retain
users are at least as computer savvy as integrity: Design is function. Approach-
we technical communicators m i g h t be, i n g modular content f r o m a structured
fewer and fewer people are impressed w r i t i n g perspective logically breaks the
by nice f o r m a t t i n g and book covers. content down i n t o topic types that can
We've k n o w n for years that most be explained by the D I T A terms concept,
people d o n ' t use the table of contents reference, and task. O u r focus should be on
i n o u r books o r o n l i n e help, b u t y o u how we can parse information into logi-
can still f i n d tons of PDFs that are nei- cal pieces or topics, w i t h the simple goal
ther i n d e x e d n o r composed in a way of describing what, why, and how, and
that makes locating i n f o r m a t i o n easy. providing specifications of parameters,

September/October 2008 intercom 11


writing & editing

options, and other technical details. You Regardless of our experience, we that must be met before a task can be
can p u t the pieces together in various can focus on our approach and t h i n k p e r f o r m e d are easier to understand
ways to b u i l d various types of documents, t h r o u g h ways to make it better. For i n - when spelled o u t as prerequisites or list-
much like you can b u i l d a dinosaur, a stance, I have analyzed content in what ed as the first steps of the procedure.
bridge, or a spaceship w i t h Lego blocks. 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-
Concept Topics i n g " that) and f o u n d that some of the i n - uisites necessary to do something, be spe-
W h e n we set o u t to write about an 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
idea, we should concentrate on its rele- in a procedure. Often the procedure clear about how to do it. It's i m p o r t a n t
vance to the user. Before w r i t i n g about a already existed and was m u c h i m p r o v e d to provide a context that makes clear the
concept, t h i n k about the bigger picture. by adding the couple of steps, and re- need to p e r f o r m the task. If reusing part
W h o is the audience? W h a t will the us- m o v i n g those steps f r o m the concept i n - of a concept topic (or glossary term and
ers do w i t h this information? What is i m - 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
portant to explain in order to facilitate concise and digestible. Requirements it in the i n t r o d u c t i o n to the steps.
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 fort
a t h i n g is (a software feature, for exam- To reach your team's
p l e ) . Some users want a b r i e f overview potential for efficiency
and others want a deeper understand- a n d productivity, every-
i n g . A best practice for w r i t i n g a concept one must be involved.
topic is to start w i t h a concise d e f i n i t i o n For reuse to be a reality,
that m i g h t be used in a glossary and t h e n each writer a n d editor,
give m o r e in-depth i n f o r m a t i o n so read- for example, should fol-
ers grasp the framework w i t h i n w h i c h low structured w r i t i n g
their use of a f u n c t i o n makes sense. A guidelines and develop
concept illustrated by a graphic a n d / o r topics that can stand
an example has the best chance for suc- alone as well as be used
cess, because the content is designed to as b u i l d i n g blocks w i t h
speak to a variety of readers—those w h o other topics. Following
are m o r e visually stimulated, those w h o are some best practices
need the tangible effects only real-life for approaching m o d u -
scenarios can give, and those w h o j u s t larity f r o m a structured
need the tightly written glossary defini- w r i t i n g perspective:
t i o n that presents the i n f o r m a t i o n in a
nutshell. Engage
Involve the team: Every team member's participation is valued.
Task Topics Invite discussion: Each person has a say in developing the process.
N o w that I understand the purpose of Interact regularly: Get together as a team to check progress and discuss.
a software feature, how do I use it? Tech-
nical communicators are best k n o w n Elicit
for w r i t i n g procedures, so when we hear H o l d regular meetings: Make it a p o i n t to learn together h o w to improve the
about parsing content i n t o a task topic, process.
we feel we've been d o i n g that successful- Use real examples: W o r k together to improve real content for a real product.
ly for years. A n d perhaps we have. Those 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
of us w h o have conducted usability test- spin o n the golden rale will make content easier to share/reuse.
ing, whether official (using a lab, paying
thousands o f dollars to get certified, fol- Exhibit
lowing precise procedures) or unofficial Deliver products on schedule: F o l d structured w r i t i n g i n t o your process while
(having various folks outside the team 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.
o r department r u n t h r o u g h procedures F o r m a prototype sub-team: Have a few team members w o r k on prototypes to
to f i n d p r o b l e m spots or errors), m i g h t share.
already have some insight i n t o how we 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
can continue to improve the instruc- content types and gaps t h r o u g h the e d i t i n g process.
tions we write.

12 intercom September/October 2008


writing & editing

Reference Topics need a f o u r t h or fifth type. I n such cases


T h e topic type we seem to have the you should consult w i t h an i n f o r m a t i o n
most trouble understanding is in a way architect or do some research on the
the most i m p o r t a n t for technical com- current t h i n k i n g o f the D I T A experts
municators to i m p l e m e n t , because it (regardless of whether y o u are using
is often the most substantive and the D I T A ) to learn about the logic of, say,
least intuitive. The really g o o d stuff—
technical details, parameters, compari-
Some of our best 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
sons that tell users why they should use
this feature over that one—is often the work happens team to approach the w r i t i n g process
f r o m the same logical perspective. (For
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.
when we write to suggestions on how your team can best
approach structured w r i t i n g , see the
sidebar on page 12.)
In workshops where writers learn
to label content w i t h the basic three The Future Will Be DITA-like
types, people always have problems u n - Remember in the late 1980s and early
derstanding the differences between 1990s when "email" was far f r o m being
concept and reference i n f o r m a t i o n . a household w o r d , STC d i d n ' t have a
One reason is that they look the same, website, and there was no such t h i n g as
whereas task content almost always has an I n t e r n e t Service Provider? Leaders
n u m b e r e d steps. A n o t h e r reason is that in academia said the future m i g h t n o t
the content m i g h t not be written well in T h i n k i n g in terms of concept, refer- totally be U N I X , but it w o u l d be U N I X -
the first place. W h e n different types of ence, and task is guaranteed to improve like—that is, the future w o u l d be open
i n f o r m a t i o n are intertwined, writers and the quality of your content, regardless and the c o m m u n i t y m i g h t be as b i g as
editors have trouble analyzing it and o f the tools you have o n hand. You will the w o r l d itself. Similarly, the future of
readers have trouble understanding it. use fewer words, w h i c h results in savings technical c o m m u n i c a t i o n m i g h t n o t be
The three basic types of i n f o r m a t i o n for your customers (who will spend less D I T A , but it w i l l probably be DITA-like,
can be explained this way: a concept time reading) and for your company because the freer i n f o r m a t i o n becomes,
topic describes why and what, a task top- (which will spend less money o n transla- the more logically we must approach it
ic describes how, and a reference topic tion) . The content will have more d e p t h so that it has an order and a structure in
provides the details necessary to make because i t will be richer, more concise, w h i c h it makes sense, regardless of how
i m p o r t a n t decisions, often involving and more coherent. it is navigated.
when and where—for example, when to W h e n y o u first attempt to parse i n - W h e t h e r your operating system is
p e r f o r m a task, configuration informa- f o r m a t i o n i n t o the three topic types— U N I X is irrelevant, because the Internet
t i o n (settings, options) to keep in m i n d , especially when revising legacy content is b u i l t on the idea of openness. You can
and technical details, specifications, or to be more m o d u l a r — y o u ' l l come across use anything to get to it. A n d even if y o u
parameters to consider. i n f o r m a t i o n thatjust doesn't seem to fit. d o n ' t t h i n k you understand D I T A o r
But as you t h i n k it t h r o u g h , the camou- CMS or this or that other t o o l or medi-
Quality through Process flage o f wordiness will disappear, y o u ' l l u m , i t doesn't matter when y o u write i n
G o o d w r i t i n g looks effortless; howev- tease o u t the separate threads of m i x e d such a way that your customers get the
er, as we all know, it is h a r d work. W h e n i n f o r m a t i o n types, and y o u ' l l find that i n f o r m a t i o n they need. B u i l d i n g quality
we approach o u r w r i t i n g in the same most i n f o r m a t i o n can be classified as i n t o your processes can help your team
way other parts of o u r businesses ap- concept, task, or reference. Gaps in log- reuse content and save time and money
proach their functions (marketing, soft- ic will reveal themselves; content that by being more efficient and productive.
ware and hardware development, oper- seemed sufficient will clearly need more Tools come and go, b u t good w r i t i n g
ations, support), we provide solutions to attention if users are to have the best b u i l t on g o o d logic is always in style. ©
o u r customers. In the case of technical chance o f getting what they need. Fill-
communicators, some of our best w o r k i n g in these gaps is one way of prevent- A professional technical communicator for
happens w h e n we write to prevent prob- i n g problems for your customers. about twenty years and senior member in the
lems, and using the logic of structured It is best practice to focus on the three Atlanta chapter, Debbie (lmnop@mindspring
w r i t i n g we can accomplish this. T h i n k content types and discuss as a team how .com) has been active in STC as a presenter,
about it. Does your team find it needs to handle what appear to be exceptions. judge, and award-winner. She has worked as
more and more troubleshooting docu- I n some cases, brainstorming with fellow principal writer, multimedia specialist, direc-
mentation? W h a t can you do to b u i l d team members m i g h t help you see the tor, manager, and trainer and is currently
quality i n t o your w r i t i n g process that i n f o r m a t i o n in a fresh way. Sometimes, most happy in her role as information archi-
will result i n more satisfied customers? you m i g h t determine as a team that you tect at Sun Microsystems.

September/October 2008 intercom 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