Snippets and Variables

The content that technical communicators write often varies or repeats. For example, you might write a help system for a product called Longhorn and refer to the product by name throughout the help, only to have to change the name to Vista for release. Or you might write a Note in one topic and re-use it in twenty other topics, only to learn that you have to change the note’s wording everywhere for release.

There’s a familiar solution for these problems - search and replace. For example, search for the word “Longhorn” and replace it with “Vista”, or find and replace each instance of the note. But this solution isn’t perfect. You might miss an instance of the old term if you mis-spell it or use the wrong case. Or you might have to replace the note with a new version in multiple topics, so you have to copy the new note text, search for the old note, find and select it, and paste the new version over it. This is simple, but calls for a lot of concentration. Variables and snippets, offered by most mainstream authoring tools, are a better solution.

A snippet is a more powerful form of variable, so I’ll start by defining a variable.

A variable is just a placeholder with a name and a value, such as a variable with the name ProdName and a value of Longhorn. If you insert this variable wherever you’d normally have typed the product name, Longhorn, you’ll see the variable name but the reader sees the value – Longhorn. And when the product’s name changes to Vista, you just change the variable’s value to Vista in a variable control file. That change instantly applies to the entire project, “Longhorn” changes to “Vista,” as long as you inserted it as a variable rather than typing it. This offers two major benefits:

You can easily change a piece of information, like a product name or client name, across an entire project. You can also easily eliminate mis-spellings of repeated terms. If a term is mis-spelled once, it will be wrong everywhere because the variable value was mis-spelled. This makes it easy to fix; just change the spelling for the variable’s value.

Variables have one shortcoming. They only show text; no format or style. This is rarely a problem because variables are typically inserted within a paragraph of text, so they use the paragraph style. Most problematic may be the inability to contain links, graphics, or other attributes besides text, in a variable. The solution is the snippet.

A snippet is similar to a variable but more flexible. It can include links, graphics, styles, even variables. This means snippets eliminate the shortcoming of variables, have the same benefits, and add greater flexibility. That flexibility may be enough to let snippets and variables together to act like a simple CMS (Content Management System). How?

Because help topics can call snippets, you can create topics that are nothing but skeletons that call snippets. Each call to a snippet could be turned on and off using conditionality. You could also conditionalize the content of the snippets themselves. You can also insert variables in your snippets and control their values. The result is a collection of modules whose content and display can be finely controlled by using standard, simple features in your authoring tool. The real problem is managing and documenting what you did for the benefit of the next developer.

In summary, if you have to deal with content that varies, or that may vary and be inserted in many places in a project, or need to create modular content but not enough to justify the power, complexity, and cost of a CMS, look closely at the variable and snippet features in your help authoring tool.