The Magic Three: Building High Quality Content through Topic Types

Summary

The freer information becomes, the more basic structure it requires to retain integrity: Approaching modular content from a structured writing perspective logically breaks the content down into topic types that can be explained by the DITA terms concept, reference, and task. Learning to develop excellent content is best done as a team, and there are tips in this article that will help you focus on and achieve quality together. Check out this article by Debbie Doyle published in the  Intercom. Sept-Oct 2008. Volume 55, Issue 8.

The Magic Three

Concept, Task, and Reference Are the Keys to Quality – Whether or Not You Use DITA

Remember the television commercial where the kid, the mom, or the dad would snatch and then 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.

The explosion of content management systems (CMSs), authoring tools, and a variety of applications for developing, reviewing, and publishing information begs these questions of new and seasoned technical communicators: What should be our focus? Should we concentrate on which CMS to purchase? How much money should we spend and how do we select a vendor? Should we throw the same old content we’ve had for years into a wiki and hope for the best? In which tools should we invest our time and resources?

All About Content

Our focus should be what it always should have been-the content itself. The toaster isn’t a bad metaphor, because we all want the information we want when we want it. We want to search for something explicitly or generally and have the right information pop up to greet us. We want to get it while it’s hot in our minds-not too much and not too little, but just right. Good technical writing is integrating information into logical chunks that act as building blocks for larger frames of reference. Let’s put our time and thought into the ingredients of the bread and worry later about which brand of toaster to buy. The most expensive toaster will never improve the quality of the bread itself.

It matters how we write and it matters how well we write. In the world we live in today, technical communication, like the Web, belongs to everyone. Content never has truly been “owned” by technical writers, but now there is less camouflage to shadow that truth. For the most part, the role of technical writer has always been liaison between engineers and users, even when the users are engineers. Now that google is a verb and many users are at least as computer savvy as we technical communicators might be, fewer and fewer people are impressed by nice formatting and book covers.

We’ve known for years that most people don’t use the table of contents in our books or online help, but you can still find tons of PDFs that are neither indexed nor composed in a way that makes locating information easy.

Most PDFs I see don’t even have auto­generated bookmarks, much less an index, and this always makes me wonder what the author was thinking when the material was published. Did you want me to find the information I’m looking for or did you want me to read your manual as though it were a Dean Koontz novel?

Perhaps, sometimes, the matter is precisely that we aren’t thinking when we publish the variety of materials we expect users to use. We get so caught up in spelling out acronyms, consistently labeling figures, or using serial commas per style guide specifications that we forget the more important facets of a document in its users’ eyes. How easy is it to navigate to find information? And, for the purpose of this article, how easy is it to digest the information when you’ve found it?

A tool is only a vehicle, albeit a very important part of the process. Without eighteen-wheelers and other means, we wouldn’t have as many choices in the grocery store as we do today. The future will bring new fuels and new vehicles, but we’ll still need to get stuff from there to here, from here to there. Tools are only as useful as the stuff they transport. And no matter how great your wiki or your CMS or your XML editor or your PDF reader or your DITA or other architecture or for that matter your pencil or pen, it’s the content that really matters. Information mapping, Total Quality Management, Minimalist Writing, and 1+1 aren’t new concepts; they are just methods to handle the process by which people discover, assess, wrangle, and communicate information.

Design Is Function

The freer information becomes, the more basic structure it requires to retain integrity: Design is function. Approaching modular content from a structured writing perspective logically breaks the content down into topic types that can be explained by the DITA terms concept, reference, and task. Our focus should be on how we can parse information into logical pieces or topics, with the simple goal of describing what, why, and how, and providing specifications of parameters, options, and other technical details. You can put the pieces together in various ways to build various types of documents, much like you can build a dinosaur, a bridge, or a spaceship with Lego blocks.

Concept Topics

When we set out to write about an idea, we should concentrate on its relevance to the user. Before writing about a concept, think about the bigger picture. Who is the audience? What will the users do with this information? What is important to explain in order to facilitate understanding about tasks various users might want to or need to perform?

Writing about a concept requires providing an overview of why and what a thing is (a software feature, for example). Some users want a brief overview and others want a deeper understanding. A best practice for writing a concept topic is to start with a concise definition that might be used in a glossary and then give more in-depth information so readers grasp the framework within which their use of a function makes sense. A concept illustrated by a graphic and/or an example has the best chance for success, because the content is designed to speak to a variety of readers-those who are more visually stimulated, those who need the tangible effects only real-life scenarios can give, and those who just need the tightly written glossary definition that presents the information in a nutshell.

Task Topics

Now that I understand the purpose of a software feature, how do I use it? Technical communicators are best known for writing procedures, so when we hear about parsing content into a task topic, we feel we’ve been doing that successfully for years. And perhaps we have. Those of us who have conducted usability testing, whether official (using a lab, paying thousands of dollars to get certified, following precise procedures) or unofficial (having various folks outside the team or department run through procedures to find problem spots or errors), might already have some insight into how we can continue to improve the instructions we write.

Regardless of our experience, we can focus on our approach and think through ways to make it better. For instance, I have analyzed content in what might have been considered concept topics (“planning” this and “determining” that) and found that some of the information worked much better as steps in a procedure. Often the procedure already existed and was much improved by adding the couple of steps, and removing those steps from the concept in­ formation made the latter much more concise and digestible. Requirements that must be met before a task can be performed· are easier to understand when spelled out as prerequisites or listed as the first steps of the procedure.

Writing a task topic involves just 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 important to provide a context that makes clear the need to perform the task. If reusing part of a concept topic (or glossary term and definition) is helpful to the user, include it in the introduction to the steps.

Quality: A Team Effort

To reach your team’s potential for efficiency and productivity, everyone must be involved. For reuse to be a reality, each writer and editor, for example, should follow structured writing guidelines and develop topics that can stand alone as well as be used as building blocks with other topics. Following are some best practices for approaching modularity from a structured writing 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

  • Hold regular meetings: Make it a point to learn together how to improve the process.
  • Use real examples: Work together to improve real content for a real product.
  • Be a role model: “Write unto others as you’d like them to write unto you.” This spin on the golden rule will make content easier to share/reuse.

Exhibit

  • Deliver products on schedule: Fold structured writing into your process while continuing to meet the usual product deadlines; work out your process as a team.
  • Form a prototype sub-team: Have a few team members work on prototypes to share.
  • Promote modularity through editing: Foster structured writing by pointing out content types and gaps through the editing process.

Reference Topics

The topic type we seem to have the most trouble understanding is in a way the most important for technical communicators to implement, because it is often the most substantive and the least intuitive. The really good stuff –technical details, parameters, comparisons that tell users why they should use this feature over that one-is often the information in a reference topic. Reference content is often displayed in table format, but it doesn’t have to be.

In workshops where writers learn to label content with the basic three types, people always have problems understanding the differences between concept and reference information. One reason is that they look the same, whereas task content almost always has numbered steps. Another reason is that the content might not be written well in the first place. When different types of information are intertwined, writers and editors have trouble analyzing it and readers have trouble understanding it.

The three basic types of information 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 important decisions, often involving when and where–for example, when to perform a task, configuration information (settings, options) to keep in mind, and technical details, specifications, or parameters to consider.

Quality through Process

Good writing looks effortless; however, as we all know, it is hard work. When we approach our writing in the same way other parts of our businesses approach their functions (marketing, software and hardware development, operations, support), we provide solutions to our customers. In the case of technical communicators, some of our best work happens when we write to prevent problems, and using the logic of structured writing we can accomplish this. Think about it. Does your team find it needs more and more troubleshooting documentation? What can you do to build quality into your writing process that will result in more satisfied customers?

Thinking in terms of concept, reference, and task is guaranteed to improve the quality of your content, regardless of the tools you have on hand. You will use fewer words, which results in savings for your customers (who will spend less time reading) and for your company (which will spend less money on translation). The content will have more depth because it will be richer, more concise, and more coherent.

When you first attempt to parse information into the three topic types­ especially when revising legacy content to be more modular-you’ll come across information that just doesn’t seem to fit. But as you think it through, the camouflage of wordiness will disappear, you’ll tease out the separate threads of mixed information types, and you’ll find that most information 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 of getting what they need. Filling in these gaps is one way of preventing 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. In some cases, brainstorming with fellow team members might help you see the information in a fresh way. Sometimes, you might determine as a team that you need a fourth or fifth type. In such cases you should consult with an information architect or do some research on the current thinking of the DITA experts (regardless of whether you are using DITA) to learn about the logic of, say, a troubleshooting topic type. The most important thing is for everyone on your team to approach the writing process from the same logical perspective. (For suggestions on how your team can best approach structured writing, see the sidebar on page 12.)

The Future Will Be DITA-like

Remember in the late 1980s and early 1990s when “email” was far from being a household word, STC didn’t have a website, and there was no such thing as an Internet Service Provider? Leaders in academia said the future might not totally be UNIX, but it would be UNIX­like-that is, the future would be open and the community might be as big as the world itself. Similarly, the future of technical communication might not be DITA, but it will probably be DITA-like, because the freer information becomes, the more logically we must approach it so that it has an order and a structure in which it makes sense, regardless. of how it is navigated.

Whether your operating system is UNIX is irrelevant, because the Internet is built on the idea of openness. You can use anything to get to it. And even if you don’t think you understand DITA or CMS or this or that other tool or medium, it doesn’t matter when you write in such a way that your customers get the information they need!  Building quality into your processes can help your team reuse content and save time and money by being more efficient and productive. Tools come and go, but good writing built on good 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.