Category: Tech Writing

BookVars FrameMaker Plugin

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.

Re-creating a Book in FrameMaker

I’m a massive advocate of FrameMaker. It’s a great documentation tool, and unlike a certain other product, it doesn’t try to read your mind and make all kinds of weird and wonderful unrequested changes under the hood without checking with you first. Or that’s mostly the case, at any rate.

I have had problems with one instance of FM storing meta data without letting me know it was doing so, or giving me an easy way to remove it: when you update a book file, FM catalogs and hangs on to some meta data about its contents that you might rather it forgot at some point and there’s no obvious way to make that happen. The data type I’m aware of (there may be others I’ve not encountered) is condition tags.

Here’s the story: I worked on a doc set that was maintained by multiple authors. One particular chapter of information was repeated in 3 guides, and 3 versions of the content were being maintained separately, so we decided to merge the chapters and reference a single file from all 3 book files. Huzzah for efficiency!

When we started the merge, though, we discovered that the 3 chapters used different condition tags that all did the same thing. This hadn’t been an issue before as each book was maintained in isolation, so once conditions were the same across all files in the book, that was fine. Once you started using content from one book in another, though, things started to get messy.

In anticipation of merging/reusing further content, we decided to spend some time standardising the condition settings across the full doc set. We agreed a common naming and formatting scheme for the conditions and updated all content files to use the new conditions. Job done.

Well – no. When it came to updating the books, the Show/Hide Conditions dialog now showed all the old condition names plus all the new condition names, and there was a bit of confusion over why they were all still appearing. Had we missed a reassignment/deletion somewhere? We couldn’t find it on Body pages, so started trawling Reference pages and Master pages to no avail. If we were going to be stuck with all the conditions being listed, how would we remember which ones were current so that our Show/Hide conditions were guaranteed to be correct?

After a bit of googling and experimenting, I discovered that FM book files retain meta data about the conditions used by the files within the book, and the only reliable way to get rid of the data was to re-generate the book. Great.

I tried:

  1. Create new book.
  2. Drag files from old book.
  3. Save new book.
  4. Check Show/Hide settings (unwanted conditions gone – yippee!)
  5. Regenerate book.

Uh oh – the generated TOC from the original book was now static in the new book.

OK – so I’d just recreate the TOC and all would be fine. But TOC setup information, titles, headers and footers, custom page layouts and the like were lost, and making sure everything was set up correctly again would mean spending more time than I fancied verifying every detail against the style guide and templates.

I was starting to wish we’d never started making things easier.

Surely there was a sneaky way I could just convince the new book file to use the old generated file again?

So, to cut a longer than necessary story short, after some trial and error, I came up with the following:

  1. Back up your project just in case – this should be your first step in any significant book-level operation.
  2. Click File | New | Book to create a new blank book.
  3. Open the old book and drag all files (static and generated) from the old book to the new book.
  4. Close the old book without saving (just in case).
  5. Save the new book. You can replace the old book if you like.
  6. At the book level, click Add | Table of Contents.
  7. Click Add on the Set up Table of Contents dialog – don’t worry about selecting paragraph tags to include yet.
  8. Click Update on the Update Book dialog.
  9. Close the generated TOC file without saving.
  10. Copy the name of the old TOC (now a static file in the new book), delete the static file from the book (but not the disk), and rename the generated TOC file to the old TOC file.
    If you don’t remove the static file from the book before renaming the new one, FM won’t let you reuse the file name.
  11. Right-click the TOC file and click Set up Table of Contents.
    The Set up Table of Contents dialog shows all paragraph tags in the guide on the right hand side. There’s a <paragraph tag>TOC paragraph tag for all paragraph types that were included in the original TOC, so scan through the list and add the non-TOC version of each of these tags.
  12. Click Set on the Set up Table of Contents dialog.
  13. Update the book.

Ta dah! New book, superfluous meta data gone, lovingly fine-tuned TOC file preserved, in a fraction of the time it might’ve taken.