An "Interesting" WinHelp Development
On July 1, I wrote an entry describing what WinHelp is and discussing its drawbacks, such as:
- Possible security risks from its use of macros.
- Its lack of "web-ness".
- The declining number of authoring tools that support it.
- The declining number of authors that know how to use those tools.
- The declining number of authors who know the codes in case something goes wrong in the tools.
For those companies that still do WinHelp, the projects are becoming increasingly unstable. In my experience, most WinHelp authors today follow instructions written by long-gone predecessors but don't know what's happening under the hood.
Fortunately, there's always the authoring tool vendor's tech support. It's inefficient, since the support rep rarely knows WinHelp and has to research the answer in the company's knowledge base, but you'll get an answer. Until last week...
I'm converting an old WinHelp project created using RoboHelp Classic (now RoboHelp for Word) to Flare WebHelp. Parts of the project date back to the mid-1990s so, not surprisingly, a file was corrupted. After spending an hour in the code, I called Adobe tech support to see what they had in the knowledge base. After some discussion, the support rep told me that he had found nothing!
It's risky to read too much into one episode. It might have just been sheer bad luck on the support rep's part. But it was also clear that he knew nothing about WinHelp. Why does this matter?
It matters because it means that the help-of-last-resort for WinHelp authors just got wobbly. If your tool vendor can't help, it means that any conversion from WinHelp to HTML must go flawlessly via the authoring tool because, if anything goes wrong and you can't find a consultant who knows WinHelp, you'll be stuck. To me, this is a glaring signal that it's time to start leaving WinHelp now.
Tuesday, October 30, 2007
Monday, October 8, 2007
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.
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.
Subscribe to:
Posts (Atom)