One of the single sourcing features I’ve used most in FrameMaker is variables. These are nifty little placeholders you can stick into your documents to say “put the product name here”, “put the company name here” and the like, then when it comes time to publish a book, you can set the required values.
Variables save an innordinate amount of time when it comes to rebranding common material used across a large documentation set. Consider a couple of typical scenarios based on real life experiences:
- One company releases multiple versions of a product under different names with 60-90% common functionality in each of them, but the main product name and a few of the component names change for each version.
- Another company announces the night before a release that they’ve decided to change the product name. Unfortunately, the product name includes the company name, so a straight search and replace isn’t good enough – each and every one of 1000+ occurrences of the name must be checked before making any edits.
In either of these scenarios, but especially the second, variables are your friend.
Once upon a time, I managed variable settings for different releases by having a single FrameMaker file for each release, with the appropriate permutation of variable definitions in each file. This is a reasonable strategy, and works well for small doc sets.
When doc sets start to get bigger and more complex, it’s a less manageable solution. For example, say your company rebrands and changes its name. If you’re using a variable for company name, and have 30 FM files with custom sets of variable definitions for 30 possible release scenarios, you have to make that substitution in 30 locations.
That’s when Leximation’s BookVars plugin becomes a very attractive option.
I discovered this plugin last year when I worked with a company who were already using it. At the time they had one BookVars config file per book, which is largely equivalent to what I’d been doing with the custom FM files before, but while I was there we fine tuned variable usage across the doc set and set up a single common BookVars config file for all release scenarios.
A BookVars config file contains one or more named Groups of variable definitions. When you’re ready to publish your book, you select to import the variable definitions for one Group across all files in the book, and away you go. Better still, any Group can reference any number of other Groups in the same config file, which means you can, for example, have:
- A Universal variables Group (company name, current year, etc.).
- Product-specific Groups (product names, names of components within the product, etc.).
- Release-specific variables (publication date, version number, etc.).
There’s an enormous amount of potential there to cater for all manner of scenarios.
The other key features we got some value from when creating our common BookVars config file were:
- Deleting unused variables across the current book. This allowed us to weed out all the legacy variables no longer in use before standardising usage across the doc set, and to get rid of leftovers at the end once we’d renamed and/or substituted several others.
- Renaming and replacing variables. This allowed us to deal efficiently with duplication, a common issue in larger doc teams.
- Deleting infrequently used variables. This allowed us to convert a few variables that were used only once or twice across several thousand pages back to text to be edited manually in the guides in future.
BookVars is ideally suited to projects where you spend an hour or two setting up and double checking variable usage for each release. Depending on the complexity of your doc set, it could take anything from a few minutes to several days to analyse your variable usage and distill out one or more useful config files, but the payoff, if you get it right, is a 2 minute setup time the next time you publish, which can be a very worthwhile result.
ETA: I forgot to mention pricing. BookVars is free to try, $35 for an individual license, or $525 for a site license covering 25 users. If you’re dealing with a doc set complex enough to warrant using the tool, it’ll pay for itself very quickly at those prices.