DITA Conref Push: The Other Transclude

[00:00:00.310] - Liz Fraley

Welcome to the TC Dojo from Single-Sourcing Solutions. The TC Dojo celebrates the Dojo, a place of learning and meditation. When we created the TC Dojo, we did extensive research to be as faithful as possible to the historic and cultural traditions and intent behind them. The interior and exterior images are in the Japanese to minimalist architectural style, minimalism being an important practice in technical and professional communications, it can be found in architecture, art, and music from many different traditions and cultures. The TC Dojo is a public works project for the tech comm community.

[00:00:31.510] - Liz Fraley

It's driven by you. Through the survey, you tell us what you want to learn. Instructors like Stan are community experts who are willing to share their learning on the topics you've asked for. In the open session today, we have Stan Doherty. Stan lives in Boston area and is working as a consulting user assistance developer at Oracle. He's a founding member of the Oasis Data Technical Committee, and he serves as secretary to the Oasis Data Adoption Technical Committee. He's the co-coordinator of the Boston DITA User's Group as well.

[00:01:03.130] - Liz Fraley

And I saw Stan's presentation on conref push at Convex earlier this year, and I'm glad he's here to share with us an overview of the feature and to answer questions.

[00:01:13.630] - Stanely Doherty

I don't know about anybody else, but I love getting emails and follow ups, so if something doesn't make sense here, a day later, please get in touch, honestly. Let's see. Speaker affiliations. I think Liz went through those. We're in pretty good shape. Just one little note. Something new is we're building out an Association for Computing Machinery, ACM SIGDOC. We're going to move a lot of the stuff that we had been working on at the DITA Adoption Technical Committee over there. So if you're interested in ACM and you want to join an organization as free membership, all right get in touch.

[00:01:46.750] - Stanely Doherty

So please. And they're all my email addresses. Anyway, I was always taught you want to take the main message, the bottom line and put it right on top. And so I like doing that. Conref push, what's up? And what's one of the takeaway? I'm a fan. It solves a number of tricky problems in DITA in several ways you'll see, especially in the area of managing shared topic content and especially in the area, too, where you're collaborating with organizations to which you do not have write access.

[00:02:23.050] - Stanely Doherty

So you're getting their content, but you don't have the ability to change it. It's not for everybody, and it's definitely not applicable to every or even most authoring tasks. That said, boy, it saved my bacon many times in a jam, and especially in crisis situations, and so it's invaluable if you apply it surgically and judiciously. That's it. So it's really valuable. But you don't necessarily want to have your whole staff working on it. You'll go nuts. Quick couple of slides and resources. There's some wonderful write ups of conref push.

[00:02:58.270] - Stanely Doherty

You can certainly go to the 1.3 Spec. When you get the slides and follow these links, you'll see LearningDITA (Scriptorium) and the Adoption TC. We've got a conref push article. Yeah, looking good. I really want to point out to you that not only do I have slides here, but I have downloadable samples so you can download working examples of everything I talk about today, so you don't have to recreate it. You can just walk through it and make sure that it makes sense where it makes sense.

[00:03:31.450] - Stanely Doherty

These all work. You can just download them anytime, starting now. So you don't need to take wicked notes, as we say in New England "wicked notes", about the markup because you have samples of it that you can download and torture, and especially if you find other use cases for it, please share it with other people and put it up on the list. But anyway, you have reading resources and you have code resources and please, I encourage you to avail yourself of those. So we're used to conref pull as we now call it.

[00:04:02.890] - Stanely Doherty

And these content referencing technologies are all based on W3C XInclude. So the one where we're used to, since DITA 1.0, is I'm inside a topic and I pull content into that topic from some other library topic, right. And that's your standard conref pull. I have, in my topic, code that says, "Go out and get this content and bring it to me." Right? So inside any topic, content references that are content pull references are easily auditable. There's no secrets. All the code to go out and get the other content from the library and bring it in.

[00:04:45.070] - Stanely Doherty

It's all visible. It's all there. It's all auditable and traceable. Content push came in with DITA 1.2, and it has a couple of little twists that are important to point out. First of all, there's a one to one relationship. You're supposed to just push from one library or topic into another one, right. And the syntax here, if you notice if I were to push and replace a step in another topic, what I would be doing is I would create in what we call my library or my "pusher" topic, I would create some markup.

[00:05:25.330] - Stanely Doherty

As you see here, step conaction equals pushreplace. And then so I need to say, what is the action and what is the target? What is the thing inside the target topic to which I want to apply this action. So in this case, I'm going to instruct the DITA processors at build time to go out to a topic that's named target-task-topic.dita  and find a step element that is with an ID step_first. So it first needs to find that element in the target topic, and then it applies the action.

[00:06:04.630] - Stanely Doherty

In this case, when you put the attribute conaction equals pushreplace. What you're saying is I want to substitute the following text in the command element. Open the document and I want to replace whatever is inside that command element in that step. So it sounds a little weird, but you first identify the target element by ID. You then apply the action. We have several actions, and these are the last bullet here. If you're going to really do any sophisticated actions, you need to mark the target, so you have ability to simply mark something and then apply actions.

[00:06:46.330] - Stanely Doherty

Those include pushafter and pushbefore and then you can do pushreplace. This allows you, in some cases, to do many actions. Insert, substitute, and even at a phrase level, delete, right. So it's a different logic. Again, instead of pulling something from a library, I'm developing a topic, a "pusher" library topic, and I'm defining the content that I want to change in one other target topic. Let me go into some of the details on it. By the way, not all of these are documented in many places, so I learned this mostly the hard way.

[00:07:32.410] - Stanely Doherty

For the "pusher" topic, this is the one I write and it has content I want to put someplace else in another topic. For each operation, there can be only one "pusher" topic, so I can't have one "pusher" topic and have it change 20 other topics. So it's not a global search and replace or a global change. So you can't change multiple topics from one "pusher" topic, right? The element being pushed from your "pusher" topic must be the same type, DITA or more specialized than the target, so you can't swap an ordered list for an unordered list, stuff like that.

[00:08:10.930] - Stanely Doherty

You really have to be aware of what you're pushing and why.

[00:08:15.070] - Stanely Doherty

And lastly, the library "pusher" topic it must be referenced within the scope of your map, your root map. See, because the route map and process time, build time needs to know this is something that you want to apply, so you can have these libraries sitting around, but until you put them in your map and reference them with a resource only processing role, they're just sitting there doing nothing. You see? So you enable them when you add them basically to your map and apply that resource only tag.

[00:08:44.950] - Stanely Doherty

A couple of other things. If you use the key to reference it, the key definition also must be referenced within the scope of the build. So if you create a unique key thing, make sure it's in the scope, the content cannot be pushed as a range, so there's a little limitation to content push that you don't have with content pull in that you can't send whole ranges and identify stuff like that. Lastly, you can delete the content within a target element, but you cannot delete the element itself.

[00:09:20.170] - Stanely Doherty

Remember, you can swap in, for example, the content for a command for a step, but you can't delete the step itself without creating a validation error on the target side.

[00:09:32.890] - Stanely Doherty

I mean, you can try it, but you'll just get an error. See? So this is tough. Just keep in mind as you're experimenting with the library "pusher" topics. And again, if you download the samples, you'll see painful examples of all of this every kinky little DITA thing on conref push is in there. So what about the receiver topic? And a note here it's important is many times conref push is useful in a situation where you do not have access to the sources you want to change. So if I'm in a big company like Oracle or IBM or something, there are situations where I can get topics from another organization, another group, but I do not have the ability to change them in their CCMS or change them on Git, right.

[00:10:20.050] - Stanely Doherty

So what I'm doing is I'm pulling in topics and I cannot change them directly. I cannot filter them directly. My only option if I need to change them is to use something like conref push. So if organization A sends me a topic and that topic has IDs, I can use conref push to change it for my customers without actually changing their sources. And that's both wonderful and really frightening when you think about it. So this receiver topic, if I'm getting it from another organization, what's the deal? What needs to be in there?

[00:10:59.410] - Stanely Doherty

Every element that I might want to change has to have an ID, standard DITA stuff. The target topic can receive multiple changes. So if I have five little "pusher" topics, I can make five changes to one topic that's coming in, so my receiver topic. It gets tricky, point C is that if you're applying all these changes at once where you have in your build stack in your build sequence, right, the precedents where you have your "pusher" topic affects the sequence in which things get changed and it will do the first change.

[00:11:35.290] - Stanely Doherty

It will not affect multiple changes on the same element. You need to gain a little bit of experience in some of this and what you want to change. This is why this is a little bit of an advanced feature. So we had previous slides where what do you need to do into your library "pusher" topic. And these are some best requirements, best practices. What do you do on the receiver side? So the next few slides are. So what? I'm able to go off and I'm able to make changes to the topics.

[00:12:07.510] - Stanely Doherty

What's the deal? So why use this? You can replace one or more elements in an important section. I don't know about you, but when things go south and engineering or UXD changes something at the last minute, the procedures I loved so much and have sent off to translation and I can't change them yet, sometimes have commands that are wrong. The name of something has changed, whatever. So I can make surgical changes by swapping in an updated step and a procedure or an updated list item for the one that I sent out to translation.

[00:12:43.090] - Stanely Doherty

So the sources have not changed on the actual topic itself. But these conref push libraries are making substitutions, so that's fairly common as a good use case. I don't know about you, but our API stuff is all run with these tricked out API managers like Swagger and stuff like that. So we have a body of content that is generated from these systems, these API systems, and we have a body of information that's written by writers. And right now it's very difficult to meld them easily.

[00:13:18.610] - Stanely Doherty

With conref push, you can actually insert either the system stuff into human topics or the human content into system topics simply by adding IDs and writing these conref push library. So if I were writing a tutorial and every night Swagger generates the examples or some of the API reference information I want to reference, right. It's a little tricky to try to do conrefs and all that stuff. It's not a big issue with conref push. I mean, I can just create little text files and then bring them into the code block using conref push.

[00:13:55.210] - Stanely Doherty

Go find this, go find that, go find the other thing. So in our world, conref push is interesting in that boundary between system content and human content. If you think about it and architect it a bit, you're going to get some crossover. You're going to get some cross fertilization and this particular use case, the one of doing system generated content into a human authored topic, and vice versa is the first exposure I did production wise. That's is about five, six years ago, and anyways, it was really successful.

[00:14:29.170] - Stanely Doherty

You can also remove phrase level elements. So if I, for example, had a cross reference to a topic that's whacky or broken or wrong, I can actually remove a phrase that contains the cross reference in it. I can't remove the element that's the container, but I can actually just insert an empty space, right, where there used to be an element, for example, a cross reference that I want be gone forever. So if I had a cross reference inside a phrase or vice versa, I can actually remove those phrase level sub block level elements.

[00:15:10.630] - Stanely Doherty

And when it comes to broken cross references, this is good, especially in the end game. And lastly, you can insert one or more elements. Missing steps, align an item. Just tag. Here's where I want to insert it with an ID and put it before or after. You can even add badges. So if a group is a Windows only group and they're sending me stuff and I'm a Linux person or Linux user, and I want to just add a little badge that says, for Linux users do this, I can do that.

[00:15:41.590] - Stanely Doherty

I can create badges and insert them, or I can just put little notes like this, so that my version of the topic has additional information or supplemental information that was not in the original sources to which I do not necessarily have access. This just gives you a flavor. And as you can see, a lot of it's very tactical. It's a little bit here and a little bit there, but in the endgame, when you're trying to get something out the door or if you're in a continuous publication, continuous integration environment, it's the little stuff that gets you.

[00:16:17.530] - Stanely Doherty

It's not the big stuff. So having conref push in your pocket is good. There's some challenges. Technical challenges. The data spec mostly focuses on edge cases and not the common cases. Again, I would download some of these samples and you'll see the common cases. Error handling is not strong, which means it sucks, right. Sometimes you get messages on some of the stuff that doesn't work. Sometimes you don't. So you really can't 100 percent rely on your OT or your Oxygen validation messages. It's just not quite there.

[00:16:59.090] - Stanely Doherty

Cultural. These are the bigger issues. Basically, conref push is hijacking someone else's content. I'm inserting something whether they want it or not, and I'm inserting it at build time, not at validation time. So content ownership. Who really owns this content if it's being updated without their permission, right. Technical accuracy. I insert something in somebody else's topic, and maybe that's been through a tech review, and maybe it hasn't. Who owns it? Debugging. In the topic receiving a change, there's no markup, right? Again, it's been hijacked, right. How do I make sure that we're in control of this thing?

[00:17:41.810] - Stanely Doherty

And D is a biggie, just content governance. One of the questions Liz mentioned that somebody submitted earlier is how do you guard against conref push if you don't want it? And that's pretty straightforward. You just write a Schematron rule if you can. If you're comfortable with Schematron or use your editor's search and just search for these conref push attributes, right, conaction notably, and just run it every night. And if you either can block somebody from doing it where you generate an error, you're able to shut this down.

[00:18:12.770] - Stanely Doherty

So no one is able to do this. So that's way to completely globally prevent against it, my opinion. You can always write a specialization stuff, but there's some overhead there, but yeah, if you get to the place where your team is not ready for this and people are experimenting with it, and you have no ability to monitor or govern it. Yeah, I would shut this sucker right down and buy some time to actually address these issues because these are cool issues to talk about.

[00:18:45.110] - Stanely Doherty

All right, let's see. How I'm doing on time. So best practices. So that was the negative side things to worry about. That said, there's some good stuff here. How do you make it more manageable? How do you make it something that's valuable for your team? I don't lead with this, right? And say, "Hey, we have this wicked esoteric top thing and did a conref push and you're going to love it." I can guarantee having made the mistake of pushing conref push that that won't work.

[00:19:16.430] - Stanely Doherty

You want to wait until something blows up and you have a use case for your team for your content for your organization that justifies exploring it. Say, so don't push literally, wait for something to come that looks like it might be a problem is worth exploring with conref push. Take a look at conref push how it helps your shared topics. Sometimes getting agreement on shared topics, especially mature ones, can be a bureaucratic nightmare. And if you can get the agreement to insert one little thing, here and one little thing there that makes a topic now usable across many facets or products in your organization, that's worth exploring.

[00:19:59.150] - Stanely Doherty

So just look at it. It's not a Slam Dunk, but just take a look at it. Would inserting something here or something there versus working with 25 conditions enable more general reuse on a particular topic or a particular library. Explore it. Take a look at your "pusher" topics and try to segregate them. If you're in charge of it and you put them all in one folder, it's so much easier auditing where they're going and what they're doing and when they are debug issues. So stick them in a folder or a CCMS container.

[00:20:32.150] - Stanely Doherty

Come up with some naming conventions. If you're using keys, especially, and fourth, routinely search for it. I search for conaction just to audit across Git repo or something. What are all the instances of use of conref push? Just so I know what's out there and I've got a feel for it. Sometimes if there's a writer who doesn't have a lot of experience with it, it's a good coaching or mentoring opportunity as well, but routinely search for it, right. And number five to be practical. This is one of those sharp tools things.

[00:21:09.290] - Stanely Doherty

If you don't use it judiciously and have a governance model, you're going to cut yourself as often as you cut the breakfast sausage or whatever you're getting. So you might want to limit its use to your lead writers, your IAs so that...they understand the consequences sometimes of doing something and they're in a pretty good position to do debugging. So don't push it too hard. Let the context find you and be very assiduous about monitoring and managing it. And if you're doing this, this is pretty good stuff.

[00:21:45.770] - Stanely Doherty

It'll work, right? That's about it. So that's what I had, Liz, for the best practices and way to do it. I hope it didn't go too too fast, but again, I was hoping to get through an overview of it, invite you after this to go on and work with those samples and go from there.

[00:22:07.710] - Liz Fraley

Wow. It was great, but I think I still have more questions.

[00:22:12.270] - Stanely Doherty

Please fire away.

[00:22:15.330] - 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.

[00:22:28.230] - Liz Fraley

The 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 expertise. See you next time.