Focus on: Content Reuse

We are pleased to present you with the next installment of our Component Content Management System (CCMS) series. This time we’re talking about content reuse. Once more, Roger Gelwicks will go into further detail about his informative tutorial featured at the beginning of the interview. So, let’s begin our mission of becoming proficient in content reuse, with Roger leading the way.

Roger Gelwicks: Content reuse sounds basic; it’s reusing content that you’ve already written. But specifically, in terms of what we talked about last time, but it’s about sharing IDs between documents.

In structured authoring, as I’ve said before, every element within a topic, for example, has a unique ID. Let’s say you have a paragraph with an ID of 47253. If you want to use that same paragraph somewhere else, and you’re using Paligo to do that, technically what you’re doing is you’re using 47253 in another document.
There’s no master paragraph that we’re talking about here. The paragraph just exists in multiple places.

Now, say I decide to change the ID. If there was a paragraph in one topic and then I decided to reuse it in another document or another topic, and I changed the ID for one of them, then the reuse would break because the IDs are no longer shared. Because everything is in a single source, you can share the ID numbers easily.

This is one of the main differences between how a CCMS like Paligo operates and a help authoring tool. A help authoring tool is actually referencing something else when it’s reusing content. There might be other help authoring platforms that have some sort of reuse, but what it’s actually doing is referencing a master list of pre-written content. So it’s not actually a reuse in the truest sense. But in a CCMS, reuse means that we are just sharing IDs between topics with the content. That doesn’t have to be just paragraphs. That can be images, admonitions, informal topics, etc. That’s what reuse is.

Roger: Let’s start with images because I think that’s a really good example of where single-sourcing with reuse can be extremely powerful. Many products, and this could be the case for both software documentation and documenting equipment or physical goods, or hardware, the same thing applies here. You might have products that share the same information, the same screenshots or images of parts. When an image needs to be changed for one product, it’s probably going to have to be changed for other products if they’re sharing the images. So that’s where reuse can be extremely helpful. You only have to upload the image in one place. And then, if the image needs to be changed in the future, all you have to do is re-upload a new version of that image, and that will change the image automatically in every place it exists. Because it’s referencing the same image.

So, if we think of it that way, that’s an extremely powerful reuse case. If you don’t reuse screenshots, or if you don’t reuse images of parts and things like that, when one thing changes, you’ve got to go through and find every single place where that screenshot was used and change it manually. And depending on how much content you have, that could take hours, if not days, to do that. On the other hand, replacing screenshots in just one spot takes minutes.

Obviously that doesn’t count the work involved in making the screenshots and everything like that, but once that part is done, you don’t have to track down every single place where it’s located. It will just be replaced everywhere. So you can be secure knowing that it’s definitely been replaced everywhere and you don’t have to keep track of that in your head.

The great thing is that you can use an image in multiple places and you don’t even have to remember all the different places because the usage information is readily available. If I want to see all the different places that an image is reused, I can just look at the image in the browser within Paligo and it will show me all the different topics that it’s in. So that way, if I do make a change, I’ll know exactly where it’s going to be reflected. So that makes a huge difference.

Roger: There are actually a couple answers for this one. You can have situations where you have a paragraph that is almost the same in two different places, but maybe just a word or two needs to be different. In that case, I would recommend using a variable within the paragraph that’s being reused, because that way, the shell of the paragraph is the same every time. And you don’t have to make those changes every single time it’s used. Instead, all you have to do is focus on the variable and then you can fill in different values depending on what that needs to say.

Roger: Absolutely. Variables are perfect for content placeholders. They’re great for situations where you have a sentence that you want to be able to reuse between multiple products. You could have a variable that marks the name of the product. Then you could say something like, “Login to the ‘___ product name here’.” And then you can make the ‘___ product name here’ something different every time depending on the variable values that you set up in your variable set. That way you don’t have to have 5 separate versions of the logging in task for all these products. You can just write one and then fill it in with the relevant product name with the variable value later. That’s a really small example, but you can see how that logic applied to larger paragraphs or other types of content would really speed things up for your content generation.

That’s one way you can do it. The other thing to be aware of with reuse is that you can always break the reuse at any time. For example, you may have a paragraph that you initially reused, then you realize it needs to be a little bit more customized for how you’re using it. Like I mentioned before, that‌ means you’re creating a new ID for that paragraph so that they’ll be two separate paragraphs. That’s one strategy you can use: reusing a paragraph to get most of the information you want and then breaking the reuse once it’s done in the second location. Then you can modify it as you need to. Even though the reuse is broken, it’ll still give you something to start with if you want to do it that way.

Roger: If you’re brand new to content reuse, it can be tempting to try to reuse as much as you possibly can. And depending on your content, on your information architecture, you can do that, but if you don’t really know why things are being reused, then it’s not a good strategy. You always want to make sure it’s easily repeatable.

One of the things with reuse and Paligo is the assumption that you’re not going to keep this all in your head. It’s simple to find a paragraph in the reuse feature in the editor if you think you may have used it before. It takes away the guesswork of trying to keep track of all the things that you’ve reused.

On the other hand, if there’s too many things reused, then it can be much more complicated to get the effect that you want, depending on the size of your team, how dynamic your content needs to be, and how many products you have. So I always say, definitely start slowly if you’re brand new to reuse. You can always reuse more, and you can always cut off the reuse if you need to later. But definitely take small steps so you understand what’s happening, so that when you open a topic in the future, you’ll remember why something is reused or make sure there’s a repeatable process for you and your team. If it’s a reuse process that only makes sense to one person on your team, then it’s not a good reuse strategy.

Roger: One thing I wanted to mention earlier, when you were asking about types of reuse. Admonitions are interesting because that’s a situation where you could reuse an entire admonition as is, but you can also reuse the text within an admonition outside the admonition. For example, maybe you have an admonition that includes a certain paragraph. You could reuse that same paragraph somewhere else in Paligo that’s not in an admonition. So you have that flexibility. If text is in an admonition and you want to reuse it, you don’t necessarily have to reuse it as an entire admonition. You can use that particular text in other places.

The other thing with reuse is variables and profiling. These are two main ways that you can take your reuse to the next level. I’ve talked about variables already, but profiling is another great way to write one paragraph, but then only use it when you really need it. For example, maybe you have a procedure, but there’s a step that only applies to one particular product. You can use what’s called a filtering attribute on one of those steps, then mark the product for a specific market. That way, when you publish, the step will only be included when you use that profiling value. So that’s another thing that can make reuse a lot faster.

The other way you would do that, if you weren’t using profiling, is to have two separate procedures that would have almost all the same information, but one of them has an extra step. In reality, it would be much more efficient to use one procedure and have a conditional step that only appears when you publish it for a certain product. So conditions like this are another way that reuse can be really helpful. And there are a lot of “categories” for profiling. It doesn’t have to be just by product. It could also be by output type, market, vendor, country, or something else. There’s a lot of different ways you can use conditional text to your benefit or “profiling” as we call it. Whatever term you want to use, there’s a way to make that work.

Reusing one paragraph for multiple topics, variables and profiling. These are the big three that really help you reuse your content to the greatest extent.