by Michelle Carey, Michelle Corbin, and Shannon Rouiller, IBM Corporation
Editor’s Note:
This article originally appeared in the December 2007 issue of Best Practices: A Publication of The Center for Information-Development Management (Volumn 9, Issue 6, p. 129, 133-135). You can subscribe to the hardcopy newsletter or sign up for a free e-newsletter at the Center for Information-Development Management Web site:
http://www.infomanagementcenter.com/publications.htm.
Can we live without books? Certainly, we can’t live without those wonderful novels that we pick up at the airport. But we can and should replace the book with a more useful vehicle to deliver technical information, and, as editors, we can learn to help create and edit the content for this new information delivery vehicle.
In the past, technical editors worried mostly about the meaning and appearance of the text in printed books or online help. We focused on margins, font sizes and types, line spacing, grammar, punctuation, and the clarity and organization of the text. However, much has changed in technical documentation. Although we never forget the importance of clear language and style, we have shifted much of our attention to a new paradigm: topic-based authoring.
With Darwin Information Typing Architecture (DITA) and topic-based authoring, we focus first on the external text that the users read, but we must also focus on the DITA XML elements and technology that are used to produce that external text. This new focus on DITA elements and technology has re-created the role of the technical editor in the age of topic-based authoring.
Learning the DITA XML elements and technology
Editors must now focus on the content in a different way and must also review the XML elements that writers use to create that content. DITA XML elements identify content for what it is, not for what it should look like. Editors must help writers use DITA elements properly because using the correct DITA elements can ensure that search engines return more precise results for searches or help users filter through lots of information. By understanding and using the tools and technology that produce the text, we can communicate more effectively with our writers. If we use the names of elements and attributes to explain the change that needs to be made to improve the text, writers are more likely to use elements consistently.
Editors must also work with authoring tool developers to ensure that DITA contains the most appropriate semantic elements and that the DITA elements generate the appropriate highlighting (bold, italic, monospace type, and so on). One of the current challenges for editors and writers is knowing what DITA element to use for which type of content. For example, DITA has an element called <apiname>, but should we use that element for all content about APIs, such as methods, classes, and packages? Separate elements do not exist for methods and classes. Editors can step in and ask the tool developers to create more specialized API elements, such as <apiMethod> and <apiClass>.
Editing topics
In addition to strong writing at the sentence level, an effective topic should meet certain criteria. Editors should look for:
- A precise title
One topic collection from one product might be displayed with other collections from other products. Therefore, topic titles must often be more precise to distinguish them from other similar information. For example, many software products have information about security. You cannot simply title those topics “Security.” A better title might be “Database security” or “Configuring ACLs for database security.”
- Useful content
At IBM, editors try to ensure that topics are not used simply as navigation devices, but that they contain some useful content. Also, we ensure that each topic’s content is independent of other topics.
- One or more links to other topics
Users should never be stranded in a topic. You can use linking, indexes, and tables of contents to ensure that users get to the right information quickly and easily.
Editing topic collections versus books
Users of software and hardware products typically require the right information at the right time. Users no longer sit in their living rooms next to the fire and read the manual. They want easy to read, useful information that will help them complete some task right now. To accommodate our users’ expectations, we must create self-contained, reusable topics that can be packaged in small or large collections.
In addition to editing a topic, we must also edit collections of topics. Editing topic collections is not the same as editing book chapters. What’s changed for editors is that many of us rarely edit books as linear sets of information. We don’t look at how one chapter flows to another or how chapters build on previous chapters. We also no longer assume that users read the first chapter and work their way to the final chapter. For example, many technical manuals use transitions such as “The previous chapter showed you how to create profiles. This chapter focuses on editing profiles.” Such a transition never makes sense in a set of topics because we cannot assume that users read linearly or arrived at the topic through some predefined sequence. What topic writers might use instead of the transition is an imperative to the user to do a prerequisite task of, say, creating profiles. However, the topic writer cannot assume that users have read the topic about creating profiles.
Think of topics as buoys floating in a sea. The buoys are connected to other buoys, but not necessarily in any particular order. Books are typically written as if they were train cars connected linearly. We don’t want to make users get on the train and have to walk through each train car to find the right nugget of information. The editor’s job is to ensure that we provide the buoys, or topics, that users need and that the buoys are easy to find. Also, users must be able to jump from one buoy to the next whenever they need to.
To make topics easy to find in the collections, editors need to help arrange topic collections and topics within collections in ways that make the most sense to users. For example, topic collections might be organized by product or by user goals (such as administering or troubleshooting).
Picking our battles: Focus on the rules
When you are struggling to convert libraries to topics and reorganize a mountain of information, smaller things such as whether a list is compact can seem much less important to you. White space, font choices, widows, orphans, and transitions don’t matter as much in an online, topic-based world. You find that you can let go of many of your old pet peeves, and that can be liberating.
Although we were able to let go of many pet peeves, we found that others needed to be championed. In cases where DITA doesn’t provide what we need, editors must play a key role as the advocates for needed changes to DITA. We can submit requirements to DITA, or find workarounds, or sometimes both. At first, we were tempted to submit requirements for all sorts of esoteric issues. We soon found that without a business case, requirements were not going to be accepted. We quickly learned to pick our battles and submit requirements only when prudent.
For example, we submitted a requirement to add a new element inside the <steps> element for task topics. No element was available for the “To” statement to introduce a set of steps. For purposes of clarity and reinforcement, we want to introduce steps with a statement that indicates what the steps are for, such as “To print the report:”. But there is no place to put the “To” statement so that it can be part of the <steps> element. Because we were not willing to wait for that requirement to be addressed, we came up with a workaround to add the “To” statement as the last paragraph of the <context> element in the task topic. We don’t like the workaround because it separates the “To” statement from the list of steps, and therefore does not support clean reuse of the <steps> element. But we had to do something in the interim while we waited for the requirement to be addressed.
Short descriptions: Focus on the content
Change of focus spans more than just DITA requirements and restrictions. The move to DITA and topic architecture has made us question our content: Is the content pertinent to the topic? Or was it just put there to make the book flow? Do users really need it? If they don’t need it, then why are we writing it, translating it, and maintaining it?
With topics, we need topic introductions, not transitions. In the days before DITA, we rarely thought of section introductions as standard. But we’ve discovered that an effective short description can focus a topic more clearly than a title alone can. The short description should state the main point of the topic and provide useful information. For example, suppose you create a topic with a title “Links in DITA.” Instead of starting with a short description that says “This topic is about linking in DITA,” you can start with a short description that says “DITA supports inline links, related links, and map-generated links.” In this way, you are stating the main point of the topic and providing useful information that is not already found in the title of the topic.
Short descriptions are also key retrievability aids because they can appear in search results, as hover text for links, or underneath child links. Writing one or two sentences that serve all these purposes well is difficult, and so editors must provide guidelines and examples to help our writers create effective short descriptions.
Best practices for editing DITA topics
As editors, we must work with writers, with information architects, and with user experience professionals to focus on topic-based authoring from the top down and the bottom up. We must understand and work with the technology while still delivering a complete information experience based on solid information architecture principles. Here are some best practices for editing DITA topics that we collected:
- Create self-contained topics that are easily moved from one area of the information set to another and that don’t rely on other topics to make sense (after all, topics can be linked to other topics to provide that additional information).
- Edit the overall navigation structures for the topic collections to ensure that the topic collections are grouped in a way that makes sense for your users.
- Learn enough about DITA to ensure that the content is represented semantically by the correct XML elements, thereby making you, your writers, and your information more effective and efficient. Also, ensure that the DITA element generates the appropriate highlighting that your style guidelines suggest.
- Compare the rules of DITA with the rules of your style guides and know where to draw the line for both rule sets.
- Focus on the content—the content that makes the most impact and the most sense to your users.
DITA offers new opportunities for editors to improve the user experience with information. Editors are becoming leaders in driving the movement to topic-based authoring. After all, books are out; topics are in!
** IBM is a trademark of International Business Machines Corporation in the United States, other countries, or both.
