Guest Post by Dinos Lambropoulos
Maintaining documentation when a new version of a product comes along can be a daunting chore for a technical writer. When you’re dealing with tens or even hundreds of topics or pages, what’s the best way to update content consistently throughout?
The find-and-replace approach is the most obvious, and sometimes it does the job. When the documentation is extensive, though, that approach just isn’t robust enough. There’s too much room for error, and it can be slow.
Luckily, there are faster and more reliable methods that can help dispell the anxiety that so often accompanies this task. Here are a couple that I rely on.
Variables
Variables are lifesavers when you have short bits of text that are prone to changing from one version of a product to another. Adobe RoboHelp and FrameMaker are two authoring tools that use variables, but there are others.
In my work documenting software, one way I’ve used variables is to represent the names of dialog boxes. An example would be the Options dialog found in many applications. I can call my variable something like OptionsDialog and assign it a value of “Options.” I can then insert that variable anywhere I refer to the dialog. When the help topics are generated, all instances of the variable are substituted with its value.
If the developer later renames that dialog Preferences, updating my documentation is trivial; I just change the value of the OptionsDialog variable to “Preferences,” and all instances of that name in my documentation are up to date.
Here are few other situations that lend themselves to variables:
- Product and feature names: The names of products and product features seem especially susceptible to change in the software business, so I often use variables for them. Going a step further: If your product has a long name used on first reference and a shorter name that’s acceptable on second reference, you can create a variable for each.
- Cross-references: An example would be the text “For more information, see…” Using a variable for this text keeps the wording of cross-references consistent.
- Lead-in text for tips: If you normally start your warnings with the word “Caution” but later decide that “Warning” rings the alarm bells a little more effectively, using variables makes the change simple.
- Contact information: Email addresss, phone numbers, URLs, and other contact information are subject to change and are often repeated throughout documentation. Technical support and customer service contact information are just two examples.
Reusing Content
Some information is too long or complex to be handled using variables. An example would be an oft-repeated set of instructions. The information might also have special formatting, like lists or tables. In these cases, making that content reusable can make your job a lot easier.
Let’s go back to the Options dialog box example. Suppose this dialog divides its settings among three tabs—General, Startup, and Privacy—and I want to devote a separate help topic to each tab. To access any of those tabs, the user must first know how to open the Options dialog.
Do I include those instructions in each topic? I could, but what if the steps for opening the dialog change in the next version? I’d be stuck having to update those instructions in every topic.
A better way is to write those instructions once and refer to them from other topics. That way, I have only that single set of instructions to worry about come maintenance time.
There are different ways to refer to a single topic from other topics. Some depend on the tools available to you. Here are a couple of methods I use:
- Transclusion: Transclusion means displaying content from one topic or page seamlessly inside other topics or pages. Newer versions of RoboHelp have a “snippets” feature that works this way. A snippet is like a variable, except that it can store long blocks of text with formatting. You create a snippet containing the text you want to reuse and insert it wherever it’s needed.Tranclusion is also available in some wikis. You write your content on one wiki page and then insert references to that page (or even portions of that page) into other pages. The content from the original page appears in the referring pages.
- Hyperlinks and cross-references: These old, reliable standbys still work. If your authoring tools are basic, they might even be your only choices.The idea is simple: Keep your frequently used instructions in separate topics, sections, etc., and simply link to or cross-reference them instead of repeating that content in multiple topics. A reference in a help topic might look like this:
1. Open the Options dialog box. How?
2. Click the General tab.
3. Etc…
The “How?” hyperlink would take the user to the topic explaining how to open the Options dialog box.
Essentially, reusing content means breaking it up into modules that you can then tie together as needed. This concept is central to documentation standards that have emerged in recent years, like DITA. But even if you don’t use DITA, adopting that mindset is a great way to cope effectively with documentation changes.
How do you take the hassle out of documentation updates?
Dinos Lambropoulos is a technical writer based in Los Angeles.
_________________
See:
Leveraging the user-defined variables feature in RoboHelp 7
Snippets in RoboHelp 7: A new way to work smarter
