Architecting User Assistance Topics for Reuse: Case Examples in DITA
Published: May 25, 2009
Single sourcing and its pragmatic flip side, reuse, remind me a bit of the early days of the personal computer. Everybody wanted one, but many weren’t sure what they would do with a computer if they got one. Even among seasoned user assistance architects, single sourcing and reuse remain elusive concepts. I recently heard someone at an STC chapter meeting define single sourcing as producing the same document as both a Help file and as a PDF file. Basically true, but one would hope there is more to it than that.
Content reuse got its start when a technical communicator first realized a paragraph in one topic could be used in another. She copied and pasted the paragraph from the original topic into the new one. There was joy and jubilation at the innovation: “I saved time by not recomposing a paragraph that already existed. I eliminated the retyping effort, and my two topics are consistent.” The practice spread like a California wildfire in front of a Santa Ana wind. Unfortunately, as Figure 1 illustrates, early reuse efforts were primitive and could have untoward consequences. Three months later, engineering changed the user interface, causing the original paragraph to be inaccurate. By that time, the writer had moved on, and no one had a clue as to how many times that paragraph had been pasted or where. That was the day the reality of reuse slapped us in the face: Reuse is something we need to manage and, more important, something we need to plan for.
Figure 1—Early reuse efforts
In this column, I’ll review what user assistance architects mean by reuse and what its benefits can be. I’ll then describe some different scenarios for reuse and offer guidelines that user assistance architects and information developers can follow. My examples show how DITA (Darwin Information Typing Architecture) can be an effective reuse framework. But the principles I discuss go beyond DITA, and you can apply them to any structured information framework or toolset.
Again recalling the early days of the personal computer, at the time, the only application I could think of that would justify owning a home computer was that we could store our recipes on it. I’m not sure anyone actually did this, but that’s all we could come up with initially. So, in that vein, let me share my favorite grits recipe, one I call DITA Grits Casserole. In fact, let me share two versions of this recipe, one for Southerners and one for non-Southerners. Note that the only difference is the “Results” section at the end.
Figure 2—DITA Grits Casserole—the Southern version
Figure 3—DITA Grits Casserole—the non-Southern version
Well, that’s a lot of typing to produce two versions that differ only by a single sentence. One way I could minimize the work would be to create the original and save it as southern_grits.doc, then copy and paste the common text into a second file called yankee_grits.doc, where I could then add the differentiating results statement. This example would be like our original, primitive approach to reuse, which comes with a lot of headaches. For one, what happens when my editor points out that DITA, as an acronym, needs to be in all caps? I have to find the original version and the alternate version and fix it in both places. And what if I want to translate both versions? Will I have to pay twice to have all the common text retranslated?
A better solution is to have only one file that both contains the common text and specifies conditions for the variable text. Figure 4 illustrates this common technique, which is often called conditionalized text.
Figure 4—Conditional result statement
This example, which uses conditional text, embodies what we mean when we talk about reuse as a documentation strategy—specifically:
Reuse is the refactoring of content in an automated way, so we can use it in multiple documents or multiple media formats, without significant intervention by the author.
We can quickly see the benefits of reuse that meets this definition:
- write once, use many—We could include the same file in regional cookbooks, generating the Southern version for the appropriate regions and the non-Southern version for other regions that have not yet developed the proper palate for grits.
- edit once, fix many—Fix that nasty little capitalization issue in the source file and know it will be correct in all of the books that use that file.
- translate just once—We can eliminate the unnecessary retranslation of text that is common across multiple topics.
- write once, output many—Since the DITA source is in XML, we can use the same file to do an online cookbook in HTML and a printed cookbook using PDF formatting.
- get it right, keep it right—Reuse is particularly useful for golden text scenarios where you need to control the message—for example, pointing out that feature X could erase users’ hard drives if they accidentally introduced a typo in its command. Once you get marketing and the lawyers to agree on the acceptable wording, you can lock it down.
Types of Reuse
The reuse landscape is more complicated than just producing the same document in multiple formats. In fact, that is probably the least useful application for reuse. To plan and write effectively for content reuse, you must first understand the different ways in which you can reuse content and the unique considerations for each of them. There are four scenarios for content reuse:
- same content published in different media—In this case, the unit of reuse is the entire document.
- same topic in different documents—In this case, the unit of reuse is the topic.
- same content within many topics—In this case, the unit of reuse is the smallest taggable element.
- slightly different content within one topic—Again, the unit of reuse is the smallest taggable element.
Same Content in Different Media
Figure 5 shows an information center that presents an Installation Guide to users as both a PDF file and an online document. You can compare the table of contents for the online version, in the panel on the left, with the table of contents for the PDF file, in the panel on the right. They are identical.
Figure 5—Same manual in HTML and PDF files
This type of reuse can be useful if you have one format and suddenly find yourself needing another. For example, you might have all of your documentation online, then suddenly get hit with the requirement that you need a hard-copy manual to export the product into a particular market. Or you might have an extensive collection of user manuals and now need to comply with a new product management mandate that all user documentation must be in HTML.
The main requirement for reusing the same content in different media is that you separate content markup from presentation markup. Of course, one of the strengths of XML in general and DITA in particular is their use of semantic tags—what something is—such as <title> or <uicontrol> instead of presentation tags—how something looks—such as <h1> or <strong>.
The down side is that the user experience typically degrades in the transformation from the designed-for medium to the medium of convenience. In other words, a good manual becomes a not-so-good online document, and a good online document becomes a not-so-good manual.
Same Topic in Different Documents
One of the most common scenarios for reuse in my own experience has been the sharing of specific topics among various Help files and user manuals. Figures 6 and 7 show the same topic in a Help file and a Configuration Guide.
Figure 6—Topic rendered in a Help file
Figure 7—Topic rendered in a user manual
The chief requirement for topic reuse is that topics must be modular and have the ability to stand alone—for example:
- no transitional phrases such as “As we said earlier…” or “In the next section…”
- no restrictive references that limit reuse, such as using a product name in an otherwise generic block of content
- limited use of embedded links that create dependencies with other topics
In DITA, we can define links between topics in several ways:
- by creating a separate file called a DITA map—through a relationship table or by nesting topics in a parent-child structure
- by using a directly embedded link—through an <xref> tag
When using a directly embedded link, the file to which it links must accompany the file containing the embedded link. However, this type of topic dependency limits reuse. Defining links outside the topic file increases the reusability of the topic. Figure 8 shows a section of a relationship table in a DITA map that defined the related concepts and related tasks links that appeared at the bottom of the topic shown in Figure 6. The DITA map that rendered the same topic in a PDF manual—shown in Figure 7—did not contain that relationship table. Defining the links outside the topic facilitated its reuse, independent of the related topics in Help.
Figure 8—Relationship table to define inter-topic links
In short, modular reuse of topics requires a clear separation of the following:
- topic content—In DITA, this is the topic file itself.
- document structure (TOC)—A DITA map defines the structure.
- topic relationships like related links—In DITA, relationship tables usually define these.
Same Content within Many Topics
User assistance topics often share small snippets of content—for example, descriptions of common user interface elements or marketing-approved product names. These scenarios are rich targets for reuse. You can achieve this type of reuse in DITA through the <conref> tag. Figure 9 shows a short description that pulls the product name, Proventia Network MFS, from a reference file of marketing-approved product names.
Figure 9—Product name as <conref>
The main restrictions for content references are that the element in the source must be taggable, and the tagged element must be allowed in the target topic. For example, some elements that DITA allows in task topics such as <step> are not allowed in a concept topic.
Slightly Different Content within One Topic
The DITA Grits Casserole recipe at the beginning of this column is an example of slightly different content within one topic. In user assistance, this typically occurs in the following situations:
- different audiences—for example, system administrators and users
- different platforms—for example, Linux®, AIX®, and Windows®
- different products—for example, Turbo and TurboPro
In DITA, you use a ditaval file to define what rules to apply when you run a specific output. For example, to get the result in the Southern version, you would refer to the ditaval file, shown in Figure 10, when you built the output. Note that it includes any text whose audience attribute is Southerner and excludes any text whose audience attribute is Yankee.
Figure 10—ditaval file to define result for Southerners
User assistance, because of its modular nature, provides rich opportunities for reuse. We need to move from merely opportunistic reuse of content—as in Oh yeah, I think I already wrote something about that, maybe I can reuse it—to a more strategic approach—as in From the beginning, let me write this so I can reuse it later. Understanding the different scenarios for reuse and their specific considerations can help you set an effective strategy for content reuse in your user assistance.