Product Spotlight: Frederik Carette on Variables in a CCMS

One of the main benefits of a component content management system (CCMS) is that it enables you to easily reuse the same content everywhere. But what if you want to reuse the content with slight variations depending on the product, features or region? This is where variables can really come in handy.

Frederik Carette, Information Architect at Paligo, says he loves variables because they can take a topic that is otherwise impossible to reuse because it contains specific content, and turn it into a topic that can be used across your documentation. He advises clients to get creative with variables, and think beyond individual words.

Frederik Carette: It depends on the CCMS, but in general a variable is a kind of placeholder that enables you to reuse content that has slight variations. So when you’re using topic-based authoring, instead of writing a product name in a topic, for example, you insert a variable, which connects to content somewhere else in the CCMS.

Then when you publish, the variable will dynamically change the content based on which product you select for your output. If you want to produce a text about Product A, for example, then the variable placeholder will pull the relevant content about Product A. This makes it so much easier to reuse content.

Frederik: Sure, one example I use in my demos of Paligo is about candy. So I live in Sweden, but I originally come from Belgium. Let’s say I have to create documentation about candy, and I need to produce it for both the Swedish and Belgian markets.

What I can do is write an introduction topic about the history of candy that is relevant for both Sweden and Belgium, but at the end of the content I want to mention something specific about the history of candy in one of the countries. Instead of writing that in separate topics, I can add a variable for Swedish or Belgian candy, then I can reuse the topic for both documents.

In the topic, the variable will look like a visual button that includes the name of the variable, like “Swedish candy history.” Then when I publish documentation for the Swedish market, the CCMS will pull in all the related content about Swedish candy stored in my variable.

Frederik: Paligo handles variables a little bit differently than other CCMS because right from the start you have templates for variable sets already available to you. A variable set is basically a table. For example, the columns of the table could be all your product variants, like different types of refrigerators for wine, and the rows would be variables that you want to plug in for each product, such as the number of bottles of wine each fridge holds, the dimensions of the fridge, and its weight.

In Paligo, variable sets are more of a plug-and-play feature, which is a big help for writers who are new to using a CCMS. You just go to the Content Manager, and templates for variable sets are already there. You can immediately start adding all your texts to the table, and even add images and full paragraphs. I love this feature in Paligo because it’s a really effective way to reuse content and scale content production.

Other CCMS have similar functionality for variable sets, but you have to do a lot of work behind the scenes to set them up. In other CCMS, you would have to create informal topics, add content to them, then create IDs for the content, then link those IDs to empty placeholders in your text. And if somebody changes something in that pipeline, it can break very easily. This isn’t the case with Paligo, since we put all those connections in the background where people can’t touch them.

Frederik: Aside from making it easy to reuse content, variables in Paligo also make it easy to automatically update all your documentation when something changes. Let’s say that next year Product A is now two kilograms lighter. Instead of having to go through all my documents, trying to find where the weight of Product A is mentioned, I just go to my variable set and change the weight there. Then Paligo will automatically add the correct weight everywhere it is mentioned. This makes it simple to keep your documentation up to date.

Another benefit to using variables in Paligo is that we have a preview feature in the editor. So when you’re creating your text and plugging in variables, you can pop open a preview window to quickly see how your variable sets will look in the published documentation. You don’t have to create a PDF or an HTML file to see the results.

Frederik: It’s basic advice, but I always recommend that people first read their own documentation. A lot of people don’t do that, especially if you get thrown into a project as a new technical writer. It’s easy to get stuck in producing content and not looking back at what has been produced before. It can be really valuable, though, to set aside some time to read through past documentation and start thinking about what content is actually repeated.

There are some things that will always be easy to use as variables, such as product dimensions and other smaller elements like that. But you can actually play around with variables a lot more, like using a full paragraph as a variable. So I recommend you go through your documentation and underline content that is repeated, then put those repetitions into a table, then see if you can start plugging that content into variable sets.

If you come from manufacturing, you usually have a PIM system to manage your different components, and you can use an API to automatically turn that information into variable sets in Paligo. If you’re not in manufacturing, however, such as you’re working with something more software-related, then it’s prudent to read your documentation and try to discover the similarities.

Frederik: Variables in Paligo are quite a powerful tool, and they’re fun to use, but I think probably the most common mistake people make is to create variable sets when they’re not needed. Sometimes people create a variable set when they only have one product, and if they’re planning on having more products in the future, then that’s a great idea.

But sometimes people add a variable set, and three years later they still don’t need it. This creates extra maintenance and adds another level of work, particularly for reviewers who need to refer to the variable set when reading. So to prevent unnecessary work, think carefully about how you will use a variable set and why.

Frederik: Most often people think of plain text, or little text snippets, when creating variables, but there is more you can do with variables. You can also add variables that include full paragraphs, lists, glossaries and images. I’ve seen people be very creative with it. There is a lot of content that can fit in a variable set, which will save you time in the long run.

Another point is that sometimes people are worried that they will plug in variables but not be able to find where they used them later. It’s a valid concern, and that’s why Paligo has good functionality for traceability, so you can always find where variables are used.

Related to that, I suggest that people also use taxonomy labels when they add variables. Using these labels helps writers understand the context of your content. If we go back to my example of Swedish and Belgian candy, I would add taxonomy labels on that introduction topic, so the first label could be “candy” and then have labels for “Belgian candy” and “Swedish candy” under that. By doing this, when a new writer comes in, the first thing they see are the labels, and they understand that whatever they write there needs to be applicable to both of those markets.

Frederik: Over the years, I’ve worked with a lot of different types of CCMS, and Paligo by far makes it the easiest to use variables. I think it’s because variable sets are right there in the Content Manager ready to use. Variables are one of the features that should always be at the forefront when thinking of reuse, and they’re one of the things I always showcase to clients.