Extend Your DITA Reuse with Keys

[00:00:00.550] - Liz Fraley

Good morning. Welcome to the TC Dojo from Single-Sourcing Solutions. The TC Dojo is a techcom community that is driven by you. Tell us what you want to learn. You choose the topics, and we find the experts. In the TC Dojo open session today, we have Pushpinder Toor from PTC here to talk about DITA Reuse Keys. Pushpinder has been a part of the Arbortext product line for nearly 20 years. She was an Arbortext before it was acquired by PTC. She's been a solution manager, a consultant, a product manager, a project manager, senior technical trainer, and is now the Director of Product Management for the Arbortext Product Suite at PTC. 

[00:00:35.830] - Liz Fraley

She's responsible for leading the vision and strategy for authoring, creating, and managing information using the Arbortext suite of products. She spent her career gathering critical customer requirements for releases and determining product roadmaps to fit strategic customer goals. We're especially grateful she could come to the TC Dojo today to share her experience with all of us. Now, Pushpinder has a lot to cover, so she wants to save questions until the end. But be sure to type them in when you think of them so you don't forget what you wanted to ask.

[00:01:05.530] - Liz Fraley

Pushpinder, it's all yours.

[00:01:08.440] - Pushpinder Toor

All right. Thanks, Liz. So Liz actually gave me a really good introduction already. But this is, I understand that with the Dojo, it's a very small session where we're going to focus this week on the DITA Reuse with keys. So I have a very short agenda. I'll talk a little bit about me. We'll talk about what DITA Keys are. I'm not going to go too much into depth in the the standard definition of this, because I think what really makes sense for DITA Keys is actually see them in action.

[00:01:37.810] - Pushpinder Toor

So I'm going to go through a use case example. And then I'm going to give you an introduction to my demo where I'm going to describe what I'm going to do, because sometimes when you're doing a demo, you're flying back and forth between windows. So I want to describe what I'm going to do and then I'll physically show you within the product how that works. And then, as Liz said, we'll save the questions for later just to make sure I get through everything.

[00:02:00.970] - Pushpinder Toor

So as was already mentioned, I've been a part of the industry. I've been a part of Arbortext slash PTC for twenty years now, which is pretty amazing for me to say. I've been through all sorts of different roles and today I'm actually in product management, so I'm responsible for the whole product portfolio for Arbortext. So that includes everything from editor, styler, APP Publishing Engine, all of that, the whole gamut there.

[00:02:25.840] - Pushpinder Toor

I am based out of Ann Arbor, Michigan. For those of you that have dealt with Arbortext for years, you know that that was the original starting home, founding home of Arbortext. And I am still based out of here. And Arbortext in general, just since we're talking about DITA, I did want to just quickly mention that we were a founding member of DITA with IBM, and it goes way, way, way back. So out of those 20 years, you look back 14 of those years. And that's when Arbortext first supported DITA.

[00:02:56.230] - Pushpinder Toor

So we started supporting it in 2004. So it's been a very long time coming. And it's something that we have some robust features for in the product. And that's part of what I'm going to show you today.

[00:03:09.400] - Pushpinder Toor

So the first description of just what are DITA Keys. So just from a very basic understanding. So your DITA Keys is just a way within DITA where you can have indirect referencing, and all you're doing is reusing a "key name".

[00:03:24.610] - Pushpinder Toor

And the point of that is that DITA  wanted a way to allow the topic-based authoring to create links to other topics. And by switching the key on or off, you can change what that content is that's going to appear. And this is huge for reuse. So I won't go through all the advantages of reuse. But being able to use keys is also a big advantage of making sure that you're taking true advantage of the reuse story. What happens is that the key that you create is bound to the actual content that you want to publish via a key definition.

[00:03:59.980] - Pushpinder Toor

And the way I'm going to show you in my demos that all of the key definitions are actually residing inside of a map. And you could point to that map and then you can switch out maps based on which key you want to use or you can do a key override. So really, as I mentioned, it's the reuse. So you're keeping the text identical, but you're referring to this kind of abstract key and you're telling it what to resolve to based on what the specific content is that you need to publish.

[00:04:26.890] - Pushpinder Toor

So there's just a quick screenshot showing. Here's a whole bunch of keys and this is what you'll see in the demo. And all of these key definitions are pointing to topics that could point to images, it could point to tables. You can point to almost anything using a key. So that's just the real basics of what DITA Keys  are meant to do and what their advantage is. So in the use case example that I'm going to show you, okay, so that's great.

[00:04:54.040] - Pushpinder Toor

It's indirect referencing, it's reuse, it's making the key resolve to itself. So how does this work?

[00:05:00.820] - Pushpinder Toor

So in the use case that we have is, let's say you have a product manual and it's for a lawnmower. And basically the lawnmower is exactly the same. It has all of the identical content except between model A to B. There's a difference in how the customer will be doing... will be following the procedure for changing their oil. There may be a difference in your recommended maintenance schedule for that lawnmower, and maybe the model itself has a little bit of a different look to it.

[00:05:30.610] - Pushpinder Toor

So everything else is the same. So maybe it's 90-95 percent of what you're going to tell the customer for the lawnmower is identical content except for those three pieces. So what are we going to do? We're going to share all of the content that's identical. We're going to create keys for those three specific pieces of content that's unique, and we'll create override for some of those keys based on that content. So that's what we're going to do here.

[00:05:57.900] - Pushpinder Toor

So if we take a quick look, the demo that I'm going to do, a quick introduction to the demo is they'll have a map. And the map itself is going to actually point to a structure map. And that structure map is what's being reused. Okay, so that's that identical content. And this doesn't have to be two landmowers, right? It could be three, four, five. You could have 10 products that are almost exactly the same except for very specific, unique parts.

[00:06:25.080] - Pushpinder Toor

So what we've done here in this demo is we've created an entire map. That's the structure, that's a reshared structure. I'm going to show you two maps, same hierarchy. So it'll be one map for each manual for X-1 as well as X-2. The structure map will have all of the topic graphs in it. It'll have the actual depth of the structure, of what you want inside of the manual. And then we're going to have keys that are going to swap out the information.

[00:06:51.480] - Pushpinder Toor

So here's those three things that I was talking about earlier on the slide.

[00:06:56.280] - Pushpinder Toor

So based on which model you're using as my customer, you might need to change the oil differently. You might have a different maintenance schedule. And I'm also going to give you a different graphic because the product looks different. So I want to make sure that you get the right visual of the product as you're dealing inside of the manual. So that's just a quick look at how that demo is going to work.

[00:07:22.380] - Pushpinder Toor

So when you look in the demo, I'll show you side by side, and again, I'll show you all of this. But I wanted to visualize it first. Here you see, I have the X-1 user manual and I have the X-2 user manual. It's two separate models. So within my editor window, I'm looking at what's called the column view. And inside of that I have a map, and you'll see here that there's a lot of content that can be unique based on the X-1 versus the X-2.

[00:07:51.510] - Pushpinder Toor

So maybe the title is different. The book ID is a little bit different. The model number might be different, the serial number. So I can make all of that unique in there, each individual map.

[00:08:03.390] - Pushpinder Toor

But what I really wanted to point out. So if you look at that, sorry, I meant to build that. But I really want you to look at is the bottom here where you'll see that there's a structure. And you notice how it's the same structure in both maps. Right? So I only had to create the structure once and I could reuse it multiple times. Right? That's the whole value.

[00:08:23.070] - Pushpinder Toor

So my X-1 has this user manual structure and so does my X-2. What's going to happen though is I'm going to override some of the keys. So what's going to happen is that the changing oil, there's actually a key called ChangeTheOil. And what I'm going to do is I'm going to change the navigation title. So it points to the exact manual that I'm working on and I'm going to change where that key is pointing to, what it needs to resolve to.

[00:08:52.140] - Pushpinder Toor

So it'll be different in each of the manuals. I have another key for the maintenance schedule. The name of the key is MaintenanceSchedule. I'm going to change the navigation title. And again, I could change the href. I'm also going to change out the image. So the image, the key is called ProductImage. And in this case, in my second manual, I want it to point to X-2 versus X-1. So I'm just changing what it needs to resolve to.

[00:09:20.740] - Pushpinder Toor

So let me... Oops, not questions yet. Let me go ahead and show you in the product some of the demo part of this. So if we take a look here. Here is... Oops, sorry. Got too many windows going on here. Let me show you, first of all, the structure. Remember I said both of them pointed to the same exact structure. So this structure DITA map has all of these different parts. It has all of these topic references that are exactly the same.

[00:09:52.100] - Pushpinder Toor

I don't care which lawnmower. You're going to do the same thing when you're keeping the shields in place, the same thing with refueling, the same thing with the blades and the controls. All of that is similar. Okay? So this entire structure has already been built.

[00:10:07.100] - Pushpinder Toor

What's really cool about this and this comes back to all of the data standard and how you have maps with the maps and how you're changing out references, is there's actually a reference to a map called X-1 Keys.

[00:10:22.580] - Pushpinder Toor

So I'm going to open up this map. And this map has all of the keys and part of that screenshot that you were looking at. So here's that key called ProductImage. And you'll see here that it points to a reference to an X-1 jpeg, and the key is called ProductImage. And then if I look through here, let's find the maintenance schedule. And you can see here, because it's the X-1, it just says maintenance schedule. So this is an entire map of keys that is being referenced inside of the structure.

[00:10:59.060] - Pushpinder Toor

So you've already got two levels here.

[00:11:02.030] - Pushpinder Toor

Now, if I were to go into the structure for the X-1 as well as the X-2, so let me put those side by side. So here's the X-2 user manual. And let me make sure I open up my X-1. So here's my X-2, and my X-2 has that same thing and has that Acme Lawnmower User Structure. Remember the one we just looked at. Inside of that was a key map, which I'm still going to leave everything the same.

[00:11:38.080] - Pushpinder Toor

I have a map with a key definition map inside of it. But what I'm going to do is I'm going to override three of those keys because changing the oil is different. Again, the maintenance is different. The product image is different. So if you look at product image, I'm going to change it. So it's pointing to X-2.

[00:11:55.150] - Pushpinder Toor

If you look at the maintenance schedule, it's going to be a different maintenance schedule and so is changing the oil. So if you give me one moment here, I will show you the exact folders that contain this content. And inside of here... So if you look here, there's my X-2 folder, and inside of that it has its own change the oil, its own maintenance schedule, and that X-2 file. So there's that green. This one has a green lawnmower.

[00:12:30.770] - Pushpinder Toor

Changing the oil is a little bit different. And I'll put this side by side so you can see these differences here. And then the maintenance schedule.

[00:12:58.810] - Pushpinder Toor

If I go in here, I can see my changing the oil to open that topic reference. So this is changing it on X-1 and this is changing it on X-2. You could see already the navigation title was different. So there's a difference there. There's also a difference in tilting the lawnmower to the right on this one.

[00:13:22.390] - Pushpinder Toor

And this one says tilting the lawnmower to the left. Okay? So what I've done is that the actual entire procedure is being swapped out based on which particular lawnmower model that this is working on. If I look at... So let me close those out. And if I look at the structure again, there is... I go up here. There is about your lawnmower. And that up again. So in here, in about your lawnmower for X-1, it has the green...

[00:14:07.430] - Pushpinder Toor

Excuse me, the red one. And you know for X-2, it was supposed to be green.

[00:14:12.490] - Pushpinder Toor

So if I go to X-2, and there's my override definition for this product and it has the X-2 in there. So when I actually do a publish on these, it'll be a lot more clearer that these are being swapped out. But just to go back to describe this again, I've got X-1. Let me move that to the left so it matches the screenshot that you saw earlier.

[00:14:40.280] - Pushpinder Toor

I've got X-1. I've got X-2. They both have differences when it comes to their metadata. So I was able to make changes and all of the metadata, the book part number is different, the model number, the serial number, which is fine because they're two separate maps. These maps are pointing to a structure map. The structure map is pointing to a key map. And then I overrode just those three keys inside of my X-2 structure.

[00:15:07.970] - Pushpinder Toor

So if I go in here, and I'm going to do a quick publish on both of these. And if I do the publish... I have this already existing. I can go ahead and open it up in just a moment. That was my X-1. So there's my X-1 lawnmower. Okay. So there's the PDF for that. And as soon as I create the PDF here for this one, we'll compare those three things that I had described before that the keys were swapping out and changing.

[00:16:01.500] - Pushpinder Toor

Give it a moment just to resolve all of those keyref and know that what it's supposed to pull in.

[00:16:07.110] - Pushpinder Toor

But as we're looking at this, this is the X-1. So this particular model, it's supposed to be look like this red lawnmower. And if I go towards the end here, the maintenance schedule is a little bit different, specifications, all of that content is in here. So here's that maintenance schedule on the X-1. And here's the one for the X-2 model, the X-2 lawnmowers. If I go in here, there's the green that's been swapped out. And then if I do a quick...

[00:16:48.840] - Pushpinder Toor

schedule, you can see here that it's actually different where this one says, Oh, for the first 20 and the 50 hours you're supposed to change the oil on the X-2. Don't worry about it, you should only do it in the first 20 hours. And then the second part of the table's different, too.

[00:17:05.040] - Pushpinder Toor

So all of those things are different. They just put everything else in here. If I go to operating the controls here, everything else is the same. It's exactly reused where I'm not having to recreate anything. So I can change the look and feel just by swapping out the image. And you'll notice here on the cover page as well, you've got at the bottom, the different part number... Excuse me. The model numbers that I was talking about. You can replace those because they were separate maps.

[00:17:36.240] - Pushpinder Toor

And then again, if you look at the first About Your Mower, everything is the same, except for the graphic that swapped out here and then the oil maintenance schedule and everything else.

[00:17:48.660] - Pushpinder Toor

So again, I'm not having to go back and fat-finger things in. I don't have to ask somebody to rewrite something for me. I don't have to get it approved. I can deal with all the corporate guidelines. Everything is done.

[00:18:01.920] - Pushpinder Toor

And if I wanted to, I could technically go ahead and create an X-3 model by just, probably, saving the DITA  map if I wanted to do that, swap out the keys again and make those differences. So that's really how all of this is working together, changing those keys. First of all, defining the keys, which is done here, defining what the keys are, what you want to call them, what they're pointing to, sharing the structure, sharing the key map, and then swapping out which keys you needed to make unique for your content, and still be able to reuse across the board.

[00:18:40.830] - Pushpinder Toor

Okay. So, Liz, that is what I had that I wanted to quickly show and demonstrate. I'm happy to take questions here.

[00:18:49.920] - Liz Fraley

Excellent. That was great. I also noticed that, like it should, of course, it changes the cross references to the new title. It does all of that.

[00:19:00.470] - Pushpinder Toor

Yes. That is a good point, too. Yep. Sorry, I didn't mention that.

[00:19:04.230] - Liz Fraley

I see right there. Right there in that one. Maintenance schedule, Maintenance schedule X-1, X-2 on the other side. Yeah.

[00:19:13.790] - Liz Fraley

Now, it's time to type in those questions if you haven't already. And while you do, here's a look at what's coming up.

[00:19:20.500] - Liz Fraley

The TPC Affinity Groups are monthly-driven member discussion groups where the attendees present their specific challenges on topics on their mind in a confidential, supportive environment. Affinity Groups (mastermind groups) have been cited in Forbes as being extremely valuable to the attendees.

[00:19:35.680] - Liz Fraley

We have three going on right now. One is everything techcom, DITA, TBA, topic-based authoring, to the specifics of cross references or graphics. The other is product focus on Arbortext and Windchill. It's a collaborative peer-to-peer environment where everyone can lend their expertise to each other. It's been a really amazing to participate in and a lot of fun, too. The Affinity Groups are not free as a way to guarantee the dedication and commitment to all the parties involved. You can sign up at the TC Dojo website.

[00:20:06.850] - Liz Fraley

In our next TC Dojo, we have Kelly Schrank talking about productivity. She's going to show you how to use an old-school method to address modern content process professionalism. It's going to be a great session so be sure to sign up. How do you do that? Well. Go to www dot tcdojo dot org. That's a short link that will take you to this page. Scroll down to the bottom and you'll see everything that's coming up.

[00:20:30.170] - Liz Fraley

We've got some questions. Pushpinder, here's the first one. Can you show more about what keys look like in XML source? That's a good question. We'll come back to that, Rick, so that I can let her rearrange that. Arbortext  just hides the angle brackets, but is basically source. So hang on one second.

[00:20:55.310] - Pushpinder Toor

Here's one for you, Pushpinder.

[00:20:58.700] - Pushpinder Toor

Okay.

[00:20:59.450] - Liz Fraley

How low of a level would you define keys, word, sentence, paragraph, et cetera? That's a good one.

[00:21:07.890] - Pushpinder Toor

Yeah. I think that's going to have to be you can do it at any level. I'm not sure that I would ask people to do it on a sentence or phrase level. I think doing it on images and doing it on chunks of data, like these topic graphs that I showed you, is probably easier to keep track of and makes more sense. The more granular you get, the more of a spaghetti noodle it becomes, if you start swapping out specific small words or texts.

[00:21:40.650] - Pushpinder Toor

I mean, if that's how you need to build your content, and that's what switches out, like product names, product images. Those are the things that I think I've seen the most that people do at that small of a level or even Web URL sometimes, because URL might be different for a specific manual based on the product or based on who your audiences, especially for translation purposes.

[00:22:05.880] - Liz Fraley

Absolutely. I do think too, I've heard that translation doesn't like it below the sentence level unless it's something like a proper noun, like the product name or the URL or something like that.

[00:22:19.260] - Pushpinder Toor

Exactly.

[00:22:21.510] - Liz Fraley

Yeah. All right. Here's another one. Good one. If you have an inline link from one topic to a topic that is referenced by a keyref, do you have to use the key in the link?

[00:22:35.580] - Pushpinder Toor

I use to think about that one.

[00:22:37.140] - Liz Fraley

And then I got the comment here. It says,  "Yes, I know about avoiding inline links."

[00:22:45.330] - Pushpinder Toor

Why I like sitting here going, I got to visualize that one. So you have an inline... Repeat that again.

[00:22:52.050] - Liz Fraley

So it's like the cross reference, I think, that you had in the demo. If you have an inline link from one topic to a topic referenced by a keyref. Because that's really what you're doing, right? You are cross referencing the maintenance instructions, which is defined in a key. Do you have to use the key in the link? And that seems like yes. Do you want to bring that back up? I'll hit the stop share and we'll switch back to you.

[00:23:18.450] - Pushpinder Toor

Oh, yeah. Hang on. I also wanted to show the file, the keys map. Yeah, just the keys map as well. So

[00:23:25.060] - Liz Fraley

Alright so

[00:23:29.380] - Pushpinder Toor

Stop your sharing. Do you want to continue? Yes?

[00:23:32.860] - Liz Fraley

Oh, here. I hit the stop share. Now you can start again. There we go.

[00:23:36.540] - Pushpinder Toor

I should be sharing now. I just brought this up a notepad just really quickly to see what the... I think this is what you're asking for. Right? How the keys... Here's the key definition. There's the About. You can change the navtitle. I mean it's just XML, so I mean it's the same as any XML file at the angle brackets and so forth. And then at the top you'll see that it still has your DOCTYPE declaration. It's based off of the DITA Keybase or DTD.

[00:24:08.950] - Liz Fraley

And what version of Arbortext are you showing here today?

[00:24:12.790] - Pushpinder Toor

I am showing version 7.1. I believe I should be on M20 or M30... Or sorry. M21 is our latest. And we actually have M40 that will be releasing in a couple of weeks here at the end of this month.

[00:24:27.150] - Liz Fraley

Excellent. Can you switch to that the About Us in the X-2?

[00:24:35.430] - Pushpinder Toor

I have way too many windows here.

[00:24:38.010] - Liz Fraley

That is how it gets.

[00:24:42.240] - Pushpinder Toor

Sorry, so you want-

[00:24:43.530] - Liz Fraley

you want the About because that's in both places, right? And the About is in the basic structure because it's not overridden. Right?

[00:24:54.890] - Pushpinder Toor

About Your Mower, this?

[00:24:56.420] - Liz Fraley

Yeah. So you can see here-

[00:25:00.430] - Pushpinder Toor

The only thing overridden is the image. And that's because the key-

[00:25:03.840] - Liz Fraley

Well, Maintenance Schedule is replaced.

[00:25:07.560] - Pushpinder Toor

Right, that's being replaced and that's being overridden, too. That's a file reference

[00:25:11.700] - Liz Fraley

Yeah and you can see..

[00:25:11.700] - Pushpinder Toor

And it says which one are you... Yeah. And it's saying you have a key reference as well as an href. Which one do you want to open at this point? So...

[00:25:21.390] - Liz Fraley

All right. So let us know if that answers the question. All right, good. So let's see. Here we have another one. How are keys different from profiling.

[00:25:34.190] - Pushpinder Toor

It's a good one. So profiling in Arbortext is a way of... Basically, you're not swapping out information always. It's almost like you're taking, you're removing and including information, if that makes sense. So when you profile something and you say, this is a piece of text that only applies if you're using... You're creating one large file with everything in it, up front. And then you're labeling pieces and saying, this only applies to X-1. This only applies to X-2. And then you're asking the profile to say, show me what this would look like only if I was doing X-1 versus X-2.

[00:26:18.160] - Pushpinder Toor

So in that one, you're starting with everything up front. And then you're labeling what you want, taken in and out. You're not necessarily swapping the same text or the same, like I said, the product image in that case. So it is a little bit different and it's not really indirect referencing that you're doing. It's more of the content that's still held there. So that makes sense?

[00:26:45.580] - Liz Fraley

That's a great way to describe it, actually. So if you'll let us know if that answers the question and we'll follow up from there. All right. We have one similar question. And I know that Arbortext protects writers when they're doing their keyrefs also. So here's the question. How did keys differ from conrefs?

[00:27:08.390] - Pushpinder Toor

So conrefs are another DITA standard. And conrefs can get tricky, too. So conrefs is where you're literally swapping... I've really seen conrefs use more for things like lists sometimes where you have the same list, but you might want to conref steps two, three, and four to be different in one versus the other.

[00:27:34.190] - Pushpinder Toor

I think it really winds up just... The way you do keys much easily allows you to remove all of those dependencies and keep them separate, whereas conrefs, people will do conref files, they will do conref images, and they'll try to swap things like images in and out. What gets tricky with conrefs a lot of times is the management of those as well. I don't know, Liz, if you have more experience with that. We from an Arbortext  perspective, we actually have customers use XInclude more than conrefs when they're trying to pull in information.

[00:28:17.600] - Pushpinder Toor

So when they're trying to cross-reference a topic or they're trying to cross-reference paragraphs, we actually tell them to XInclude because XIncludes are a bit more cleaner and easier to track as well in a content management system than conrefs are, because you're getting inline into the content. And you're not really storing things as a separate file object at that point.

[00:28:44.660] - Liz Fraley

So we go either way but mostly we try to keep people to keys because they are safer, right. Conref can drop out. Conref can drop out. The XInclude can, too, if the file can't be found. But I like how when you insert a key in Arbortext , it also puts the conref as a fallback, so that in case the key doesn't resolve, at least you get the basic. You have the other way of fetching it.

[00:29:18.860] - Liz Fraley

So one of the people asked what content management system you're using. And I know that for the demo purposes, we're just using the file system. But do you want to mention--

[00:29:30.450] - Pushpinder Toor

Yeah

[00:29:30.540] - Liz Fraley

What you do internally?

[00:29:33.410] - Liz Fraley

Yeah. So Arbortext Editor does have a integration with Windchill, with PTC's Windchill system. So Windchill service information manager or SIM. So you'll see here, there's an Object and... I'm not sure I have this version, so I do. But anyway, what you would do is you would just use that and connect. And what I would be connecting to is Windchill. That's the one integration that we have supported out of the box. I'm not in this demo that is true.

[00:30:05.690] - Liz Fraley

I decided to keep it clean and just be able to do it on my local machine.

[00:30:12.190] - Liz Fraley

All right. Well, we have a very clearly explained. Thank you. Comment from the audience.

[00:30:18.700] - Pushpinder Toor

Thanks.

[00:30:19.540] - Liz Fraley

That's great. And thank you. Okay, I see how they work. Excellent. All right. I don't see any more questions. Thanks for coming to the Single-Sourcing Solutions, TC Dojo where it's all about you, what you want to learn.

[00:30:34.030] - Liz Fraley

Always attend a webinar live. You can't ask questions of a video. So subscribe to our TC Dojo mailing list at join dot tcdojo dot org.

[00:30:43.450] - Liz Fraley

Every month we go out and find experts willing to share their expertise based on your votes in the TC Dojo survey. Why should we tell you what to learn? You should tell us. So be sure to vote at survey dot tcdojo dot org. TC Dojo is our pleasure to host. As always, if you need more personal help, we're here to take you from the basics to expert. See you next time.