Reuse in DITA and beyond (podcast)
Podcast: Play in new window | Download
Subscribe: Apple Podcasts | Spotify | Amazon Music | Email | TuneIn | RSS
In episode 60 of The Content Strategy Experts Podcast, Elizabeth Patterson and Gretyl Kinsey discuss content reuse, how it specifically applies to DITA, and how it can benefit your organization.
“So often we see companies wasting a lot of time copying and pasting. This idea of reuse saves time and money, and then it also helps to maintain that consistency across your organization.”
— Elizabeth Patterson
Related links:
Twitter handles:
Transcript:
Elizabeth Patterson: Welcome to the Content Strategy Experts Podcast, brought to you by Scriptorium. Since 1997, Scriptorium has helped companies manage, structure, organize, and distribute content in an efficient way. In Episode 60 we look at content reuse and how it can benefit your organization.
EP: Hi, I’m Elizabeth Patterson.
Gretyl Kinsey: And I’m Gretyl Kinsey.
EP: I think we should start by defining reuse. We bring it up a lot as a benefit for structured offering and for migrating your content to DITA. What does reuse really mean, Gretyl?
GK: At its core, reuse is all about writing content one time and then reusing it in multiple places. That’s opposed to something like keeping a bunch of different copies of the same exact information or even similar information. What that does by having just one piece of reusable content is it establishes a single source of truth. That means that your content is going to be more consistent if you just have it in that one place and it lets you do things like take your existing content and use parts of that to create new documentation. You can kind of create multiple documents that reference or reuse the same piece of content over and over.
GK: An example that we can touch on a little bit, one common one, is something like safety warnings, and cautions, and things like that. You see that very commonly in technical documentation. Just kind of right off the bat is one very quick and easy way that you can see something that’s reusable. But it also might be things like a how to guide, a getting started guide, things like that that you see the same content over and over. That means that it’s probably something you should be reusing instead of copying, pasting, that sort of thing.
EP: Right. And so often I think that we see companies wasting a lot of time copying and pasting. This idea of reuse saves time and money, and then it also helps to maintain that consistency across organizations because you might have content in different locations, and it might be from different times, and you might be pulling from different times. If you don’t have all of that together and you’re not reusing it efficiently, you might have inconsistent information.
GK: Absolutely. We’ve seen lots of cases where two different writers are basically writing the same content because there’s not that communication and they’ve kind of written the same information in two slightly different ways. That introduces that inconsistency. And as you said, if there’s not really a good method of version control in place then if you go to reference some information, you just copy it out of an older version of your documentation. Then you’ve gotten something incorrect in your documents now.
EP: Right.
GK: It’s really important to have that single source of reusable truth.
EP: So we’ve defined reusable content. What exactly does reusable content look like? Could you share some examples with us?
GK: Sure. One of the ones I mentioned just a second ago was stuff like safety warnings, but I want to talk about different types of reuse that you can have and then some examples that would go with each. You can have reuse at the document level. This would be an entire publication, and this would look like maybe if you deliver packages of content with different products, but maybe with every single one they get the same kind of, “Here’s how to get started” sheet that goes with it. Or they get a little quick start guide booklet, but then the actual documentation is different product by product. But that one document is the same. That’s something that will be reused across those content sets.
GK: When it comes specifically to DITA, you can have reuse at the topic level. A DITA topic can be referenced in different DITA maps. This might look like a common introductory topic that’s used in a lot of different publications, kind of like I mentioned before, a how to sort of thing. It might be a list of common terms, or warnings, or cautions that you’re going to see. But basically it’s an entire topic that would be reused at different points.
GK: You can also have reuse at the element level, so that would be things like paragraphs, lists, notes, images, anything like that, tables. Something where an entire element can be reused in multiple DITA topics. That again goes back to that example I gave with safety warnings, that’s a very typical use case of that. Whatever that admonition is that contains your warning, your caution, whatever, might appear in multiple different places.
GK: You can also have reuse at the phrase level. For example, your company name or if there’s another kind of specific branded term, that just one word or phrase can be reused. There is a caution to keep in mind there, which is if you are localizing, you have to think about how reusing using one word or phrase would affect translations.
EP: Right.
GK: That’s why we don’t recommend just doing it all over the place. It’s really more if it is for a proper name or something that’s part of your branding. Your company name or something that you want to just make sure you never misspell, you only write it in the one place.
GK: DITA has mechanisms that support all these different types of reuse. If you’re looking at reuse at the document or the topic level, that might look like you have a main DITA map and you have a reference to another map that’s reusing that document. Or you may have a reference to a topic and that same reference appears in different maps. That would be reuse at the topic level.
GK: At the element level it might look something like using a content reference, or conref, to pull in that one reusable table, or warning, or note, or whatever that’s your one element you’re reusing.
GK: Then for phrase level, your company name, that might be supported by a key.
GK: DITA has all of these really great building mechanisms to support all of these different types of reuse and there are some ways that you can sort of identify what content is reusable so that you can tell which of these mechanisms that might be best for it. Of course, one way is that you might sort of know off the top of your head, “I copy and paste this information all the time. I know it’s reusable.” But if you’ve got a lot of content, or a lot of different people working on it, or maybe a lot of legacy stuff built up, and that knowledge is not just right there, there are also tools that can scan your content and tell you, “Here’s where you’ve got an exact match appearing 20 or 30 times throughout your documentation set.” Or, “Here’s where you’ve got a very close or partial match” and that’s where you can find if different writers have been writing the same thing in different ways over and over.
GK: With technologies like that, then it can pinpoint here is how much reuse potential that we have and then the types of reuse that might be in the content. You can take a look at that and then determine how that is going to affect putting reuse in place and what your reuse strategy is going to be when you move over to DITA.
EP: You gave a really good, clear picture or visual picture of what content reuse looks like. I want to cycle back around to talk a little bit more about the benefits of reuse. I mentioned a couple earlier, I talked about saving time and saving money, which are both huge, and then also maintaining that consistency across your company. Do you have anything else to add to that?
GK: Sure. One thing I want to talk about is localization. That’s because those time and money savings that you get really get even bigger and multiply if you have localization as part of your content workflow. That’s because if you think about how translation works, if you are translating one piece of reusable content, you’re paying for that translation the one time and then reusing it. But if you are not doing proper reuse and you’ve got that content basically copied and pasted all over the place, then you’re having to translate that same piece of content however many times you’ve got it all over.
GK: If you really maximize on your reuse potential and let’s say you analyze your content and you find out 25% of it is reusable, or even up to 40 or 50%, which is pretty typical, is reusable, then all of a sudden you’re looking at cutting way down on your localization costs. Especially if you look at a situation where the more languages that you’re translating into, the more those savings can really, really add up. That’s one of the big drivers that we have seen when it comes to developing content strategy is needing to get that benefit of reuse to help make localization more cost efficient. That’s a really big one.
GK: As you mentioned on the consistency angle, one thing I want to talk about there was that reuse can help make content more consistent, not just across a documentation set, but across an entire company. This would be a case where maybe you start with your, let’s say tech pubs department, and you get all of the content there consistent, then what about expanding outward to other groups in the organization. Maybe your training group, your marketing group, if there are any other content producing departments in your organization. I think it’s really important for a brand overall to have that consistency across all of those different groups.
EP: Definitely.
GK: There are a lot of times cases where there is reusable content, so a marketing website, or marketing slick that’s handed out at a convention, or something like that. If your product is very technical, or if it’s software, or even some types of hardware where people need to know what the technical specifications are, that might be a case where you would go into the technical documentation and reuse that content in your marketing materials. With training there’s a lot of reuse potential in organizations because as you bring in new employees and you need to train them on the product, there’s a lot of the product documentation right there that could form the backbone of a training course. Then you might just start with that information and then add how to’s, and quizzes, and things like that. Really, a lot of the content that you need is already in your documentation.
GK: I think that when it comes to helping make sure that consistency is there and really helps your entire brand look more consistent, more put together, that’s a big place for reuse to come into play.
EP: Right. Because if your brand isn’t consistent, people are going to question your company.
GK: Exactly. It doesn’t really make the customer feel very secure in your product when they see one thing on the marketing side when they’re ordering, and then when their product arrives the documentation looks like it came from a completely different company.
EP: Right.
GK: That’s really something important to consider. That’s another place where you may not think about the immediate financial benefits, but if you’ve got a more consistent brand messaging across all of your content, then that could really help you draw in more customers. Conversely, if you don’t have that consistency, it could lose customers and you may not even think about that that might be why.
EP: Right, absolutely. Let’s take a look at some specific use cases for content reuse.
GK: Sure. One that’s really, really interesting to me that we’ve worked on is reuse to deliver targeted content. We’ve done this for a few different companies. What this looks like is when you’ve got all of your customers needing one main set of content, but then there’s also custom content that’s based on things, like what version of the product the customer owns. Maybe what user role they have or what location they’re in. There could be all kinds of factors like that where based on that information they would need to get some additional content that is just for them. In this case, you’ve got a scenario where most of the content is reusable and then it’s just these little customizations. That’s an interesting thing to think about how you had set that up and deliver it.
GK: We’ve addressed this in a couple of different ways for different organizations. This might look like maybe using different DITA maps for different subsets or groups of customers. It may also look like using one main DITA map with different filters applied for different customers. In the one case you’ve got these different maps and they’re all kind of pulling from the same source of topics. And another case you’ve got just the one main map and then information is included or excluded based on the particular customer’s information. That’s a couple of different ways you can do it.
GK: Then if you’re looking at reuse at the element level, it’s also possible to have common topics and then appending that customer specific content via mechanisms like conref push.
GK: There are a lot of different ways that you can approach this type of reuse. That’s one scenario that I’ve seen that’s not the typical, “We need to save costs on localization.” Or, “We need to save costs on formatting.” Delivering the sort of targeted custom content to different groups of customers, but still having some material that’s the same across the board is a really interesting reuse case that we’ve seen a few times.
GK: Another one is reuse for rebranding. This might be a scenario where you’ve got a new company logo, or maybe you’ve got a new company name, or a tagline, or whatever and that needs to be referenced in all of your documents. If you are in some sort of unstructured environment where reuse is maybe either impossible or just very, very difficult, you might be looking at a situation where someone would have to go in by hand and copy in that new logo, or name, or whatever into every single document, which is a huge waste of time and-
EP: And very inconvenient.
GK: Yes. And people don’t want to do that. This is a case where we’ve seen this be a really big driver for moving to DITA for some companies because they don’t want to have to go through the pain of all of that manual copying and pasting. They just want to have that one reusable logo, or maybe a DITA key that’s referenced with the company name, and just have that be used in all their documents. Then if it ever changes again, if they go through another rebranding in two years, they just have to change out their logo in the name and then all the documents automatically update and they don’t have to go through and painstakingly change their branding individually across all of those documents.
EP: Right. Which would save a lot of time.
GK: Absolutely.
EP: If any of our listeners are interested in learning more about reuse and DITA, you can visit LearningDITA.com. We actually have two reuse courses. One covers the basics and then one goes into more advanced reuse mechanisms.
GK: Yes. I know that we talked through some of those on here. I mentioned using keys, conrefs, conref push, all that stuff, all of that is covered in really nice detailed how to information in that second advanced reuse course on LearningDITA. Then the first course just goes into the basics of how reuse work. If you want a nice expansion and some hands on practice with reuse, then that’s a good place to go.
EP: Absolutely. We also have a lot on our blog on reuse and we’ll link some of that in the show notes. So with that, I think we’re going to go ahead and wrap up. Thank you, Gretyl.
GK: Thank you.
EP: And thank you for listening to the Content Strategy Experts Podcast, brought to you by Scriptorium. For more information, visit scriptorium.com or check the show notes for relevant links.
About the author
