writing & editing


Concept, Task, and Reference Are the Keys to Quality— Whether or Not You Use DITA
10 i intercom SeptembeT/October 2008

writing & editing
HINk| emember the television • commercial where the
The explosion of content managem e n t systems (CMSs), a u t h o r i n g tools, and a variety of applications for developing, 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? Most PDFs I see d o n ' t even have autogenerated bookmarks, m u c h less an index, a n d this always makes me wonder 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 forget the more i m p o r t a n t facets of a docum 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 architecture or for that matter your pencil or pen, it's the content that really matters. I n f o r m a t i o n mapping, Total Quality 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 .

WHjk kid. the mom, or the


• dad would snatch and mm B i t h e n dearly hold onto the Eggo waffle the second it popped up from the toaster? If you think waffles are hard to let go of, try convincing technical communicators that the content they create belongs to the community in a variety of media.

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, because 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 generally 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 expensive 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 technical writers, b u t now there is less camouflage 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 engineers. 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 neither 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.

Design Is Function
The freer information becomes, the more basic structure it requires to retain integrity: Design is function. Approachi 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 logical pieces or topics, w i t h the simple goal of describing what, why, and how, and providing specifications of parameters,

September/October 2008



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 relevance 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 users 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 examp l e ) . Some users want a b r i e f overview and others want a deeper understandi 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 readers 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 success, 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 definit 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? Technical 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 successfully for years. A n d perhaps we have. Those of us w h o have conducted usability testing, whether official (using a lab, paying thousands o f dollars to get certified, following 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 instructions we write. Regardless of our experience, we can focus on our approach and t h i n k t h r o u g h ways to make it better. For i n stance, I have analyzed content in what m i g h t have been considered concept topics ("planning" this and "determini n g " that) and f o u n d that some of the i n f o r m a t i o n worked m u c h better as steps in a procedure. Often the procedure already existed and was m u c h i m p r o v e d by adding the couple of steps, and rem o v i n g those steps f r o m the concept i n f o r m a t i o n made the latter m u c h m o r e concise and digestible. Requirements that must be met before a task can be p e r f o r m e d are easier to understand when spelled o u t as prerequisites or listed as the first steps of the procedure. W r i t i n g a task topic involves j u s t a few simple guidelines. Focus on any prerequisites necessary to do something, be specific about what that something is, and be clear about how to do it. It's i m p o r t a n t to provide a context that makes clear the need to p e r f o r m the task. If reusing part of a concept topic (or glossary term and definition) is helpful to the user, include it in the i n t r o d u c t i o n to the steps.

To reach your team's potential for efficiency a n d productivity, everyone must be involved. For reuse to be a reality, each writer a n d editor, for example, should follow 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.



September/October 2008

writing & editing
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 communicators 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, comparisons 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. Reference 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 topic 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 informat i o n (settings, options) to keep in m i n d , and technical details, specifications, or parameters to consider. 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.)

when we write to

Some of our best work happens

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 mediu 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, director, manager, and trainer and is currently most happy in her role as information architect at Sun Microsystems.

T h i n k i n g in terms of concept, reference, 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 translation) . 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 camouflage 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 logic 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. Filli n g in these gaps is one way of preventi 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

Quality through Process
G o o d w r i t i n g looks effortless; however, 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 approach their functions (marketing, software and hardware development, operations, 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 problems, 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 documentation? 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





September/October 2 0 0 8


When Good Projects
Learn to Address Problems As Soon As They Arise
iiliiliiditiliiiiiiilttliiiilimilllimiilitiilmillliliil 1129*8
M B S . 74 51 P A U L A M KAPJLOW

i urn


INC 4626S-51G3

114 539


Sign up to vote on this title
UsefulNot useful