Skip to main content
May 17, 2021

DITA 2.0: What to expect (podcast)

In episode 95 of The Content Strategy Experts podcast, Sarah O’Keefe and Kris Eberlein (chair of the OASIS DITA Technical Committee) discuss the upcoming release of 2.0. What can you expect if you are currently in DITA? And what do you need to know if you are considering DITA?

“If you’ve been shoehorning diagnostic information into troubleshooting topics,  you’re going to have a good semantic place to put that content with DITA 2.0.”

–Kris Eberlein

Related links: 

Twitter handles:


Sarah O’Keefe:                   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.

SO:                   In this episode, we talk about what to expect with the upcoming release of DITA 2.0. Hi everyone. I’m Sarah O’Keefe and I have Kris Eberlein joining me today. She’s the Chair of the OASIS DITA Technical Committee. Hey, Kris, welcome to the podcast.

Kris Eberlein:                   Hey, Sarah. Thanks for having me. I’m delighted to be here.

SO:                   So happy to see you virtually. So today with the great opportunity to talk to Kris, we wanted to talk about the upcoming release of DITA 2.0, and in particular, talk about this from the perspective of current and future DITA users. We’re not going to do a full overview of the specification, but I will include a link to the draft specification and some other DITA resources that Kris has shared with us in the show notes. So if you need to do some basic research about DITA 2.0, you’ll have those resources there.

SO:                   But with that said, what I want to talk about today is where this is going and try and gain some of your perspective, Kris, on what’s happening here. So let’s talk about current DITA users. If I’m a current DITA user and I’m in DITA 1.2 or 1.3, what’s the most important thing? Or what are the dozen most important things that I need to know about DITA 2.0?

KE:                   Well, the first thing everybody needs to know, and this is user’s, tool vendors, the community, is that DITA 2.0 Is our first release that is not backwards compatible. For all the DITA 1.x releases, DITA 1.2, DITA 1.3, DITA Technical Committee really went to a great deal of trouble to ensure that all the changes we made were backward compatible. There just comes a time when you need to do some housekeeping, when you need to do cleanup, make changes, correct design mistakes, and have a backwards incompatible release. And that is DITA 2.0.

KE:                   So it’s going to present some new challenges that folks who have been in DITA for a while and have maybe gone from 1.1 to 1.2, or 1.2 to 1.3, new challenges that those folks haven’t experienced so far. It’s going to be a release that is well worth current DITA users upgrading to. We have added very robust support for audio and video. And I think probably for the first time, it’s going to make it fairly easy for folks to really have multimedia in their content without going jumping through some unnecessary hoops.

KE:                   And just in general, improvements to hazard statements, to simple table, and just a whole lot of nice cleanup. But it does mean that folks that are currently in DITA and who are looking towards upgrading to DITA 2.0 in the future are going to have some planning and some work to do. And the very first thing I think people need to pay attention to is performing a content audit and assessing whether their content contains deprecated items that have been removed in DITA 2.0.

KE:                   The biggest items that I think are going to hit folks with existing content, is if you’ve been using the alt attribute instead of the alt element, or the navtitle attribute instead of the navtitle element. Those attributes are not included in DITA 2.0. And if your content has them and you move forward to DITA 2.0, you’re going to see breakage. So doing cleanup of your existing content, if you have any of these items that we’re deprecating.

KE:                   And just as a side note, those attributes have been deprecated since 2010. So it’s not as if we’re pulling the rug out from under people. We’ve given notice for a long time, “These are deprecated. They’ll go away in the future.” And DITA 2.0 is that future point.

SO:                   So 10 years seems like a reasonable timeframe.

KE:                   One would hope.

SO:                   I heard a rumor about steps. Tell me about steps and what you’ve done.

KE:                   Well, one of the things we’ve done in DITA 2.0 is we have removed sub steps, instead we’ve enabled steps to nest. This was done really at the request of many, many users who said, “We want to be able to reuse our steps. We want to be able to reuse steps that have substeps, and we’re running into problems because maybe we have substeps in one topic and they need to be steps in another topic. And just this whole structure of steps and substeps is impeding our reuse.”

KE:                   And so the Technical Committee listened to that and we made that change. So I think that’s going to be a change that will really affect almost every implementation’s task topics. The good news is, that is going to be a very simple change to make across a body of content using scripting or search and replace. And the DITA Technical Committee will be producing some documentation and some scripts and some other utilities to help people do this sort of migration. I also fully expect that CCMS vendors will be providing their customers with a certain level of support.

SO:                   So basically if I have a task topic today, then my first level steps would be step and my second level of steps would be substep. And first of all, I would get rid of substep and just make it step. So I would have a step with a nested step for the second level steps. And then you’re saying you could actually have a third level of steps or fourth or fifth or …

KE:                   Oh, it could nest to the depths of being ridiculous. And I hope people don’t do that. I mean, it’s certainly possible to implement some Schematron rules that would restrict the level of steps one could do. But we know nowadays that people really … If people want to have infinite levels of steps they use the info tag and they put in an ordered list within it, and so forth.

SO:                   What this means, as you said, is that a thing that used to be a substep, which is now just a regular step, it would make reuse much easier, because I don’t have to worry about the fact that it was a second level step over there, and I want it to be a first level step over here.

KE:                   Absolutely.

SO:                   Awesome. Okay. So for current DITA users, I guess there’s also the tools issue, right? I mean, there’s, as far as I know, very little out there right now that supports DITA 2.0, because I mean, it hasn’t been released yet, so it might be asking a bit much. But that’s something to keep an eye on.

KE:                   It is. I mean, right now the DITA Open Toolkit has a certain limited support for DITA 2.0. Oxygen XML Editor ships DITA 2.0 DTDs. But yeah, as of yet, tool vendors have not started making changes to their applications. You can create a DITA 2.0 topic in your Oxygen Editor, but if you want to use their insert Table Wizard, and you’re trying to insert a simple table and add a title to it, which is permitted in DITA 2.0, you can’t do that. There’s no support in the Oxygen Wizard for that yet.

SO:                   Do you have an idea of timing? Not so much for the tool vendors, but for the specification?

KE:                   I’m hoping that we’ll have the specification and the standard released in early 2022. Or sorry, early 2023. I wish, I wish it could be 2022. And this is one of the things that folks are always asking me, “Why does it take so long?” The wheels of standards organizations turn slowly. And to be honest, that is a good thing. Standards, they, they live for a long time and you really want us to get things right.

KE:                   The reason why we’ve got about a year and a half runway from now is, although we have just about finished all of the grammar files, the DTDs, the RNG, the things that codified the rules for the standard, we’re pretty much done with that. But we’ve got a lot of editing the specification to go, and reviewing the specifications. And all of that has to happen before we kick off the Oasis approval process, which takes six to eight months.

SO:                   So if I’m a current user, it sounds as though I need to start thinking about this and doing some research and doing maybe some planning, but there’s not an immediate crisis action.

KE:                   Oh, absolutely, no immediate crisis action. It is a good time to start thinking and planning. If you’re a company with a decent sized DITA implementation, this is the time to appoint somebody to be your DITA 2.0 captain. To do research, to look at your company’s content, to think about what it means for your implementation moving forward.

SO:                   Okay.

KE:                   It’s a good time to test drive DITA. It’s a little too early for people to put DITA 2.0 In production. I think that really can’t happen until there is a little more support from tools and from the DITA Open Toolkit. Or if you’re not using the DITA Open Toolkit for whatever processor you might be using to pre-process your content, or to generate your output, your PDFs, your HTML5.

SO:                   So it sounds like that’s our action item, is to do that research and, “Hey tools people, tool vendors, we need you.” So what about the future users? So, we’ve been talking a little bit about the current users. People who have working implementations, who could be looking at this and thinking about upgrade paths, but what about the people who are just considering DITA? They’re not using it, but they’re thinking about it. Should they be planning to implement in DITA 2.0, or should they just jump into 1.3? What would be the best solution there?

KE:                   It really depends on their timeframe. If you’re starting to implement tomorrow, you need to stick with DITA 1.3. And to those folks, I would say, be very careful to not use deprecated items, to not use elements, attributes, or things that are being removed in DITA 2.0. Obviously, if you’re writing task topics and you need substeps, you need to use your substeps.

KE:                   If you are looking now and maybe thinking your implementation is going to happen six, nine months or a year from now, you might be able to use to DITA 2.0, if you’re probably using GitHub as your repository. Again, I think the tools are really going to be the gating factor for people to be able to use DITA 2.0 in production?

SO:                   It sounds as almost like you’re saying if it’s a small project that would be done in three months or six months, that’s a quick and dirty. Or not even quick and dirty, but a smaller company with a smaller content set, they might jump into DITA 1.3 and then make the move, but it wouldn’t be that big a move. Whereas if it’s a big, huge enterprise behemoth that moves slowly, this might need to be on their radar.

KE:                   Yes.

SO:                   I mean, even today.

KE:                   I think it’s good to be on everybody’s radar, whether you’re tiny, small, medium, large, or ginormous. This is the time, this is the time to appoint somebody to be your DITA 2.0 resource person, to learn about it, to do that content audit. To figure out what are all the moving parts in your DITA implementation that will be affected?

SO:                   Are there any particular maybe industries or subject matter areas where DITA 2.0 would be particularly helpful, or not helpful as the case may be?

KE:                   Well, one of the things we did redesign pretty extensively for DITA 2.0 is the hazard statement element.

SO:                   So this is warnings, danger, that kind of thing?

KE:                   Yeah. Warning, danger, caution. So very much used for machinery, for medical devices, for anything that has to comply with particular standards, like particular ISO standards around hazards or ANSI standards.

KE:                   So I think we have really listened to folks in those industries and the ways in which the hazard statement element that was introduced in 2010 was falling short. I think it’s going to be very helpful for folks in those industries. And again, also, if you really have a pressing need to have a of multimedia content, the support for multimedia we’re adding is very closely tied to multimedia support in HTML5. And so I think that’s going to be very good news for a number of implementations.

SO:                   Okay. And is there anybody that you would put on the low priority, “You don’t need to do this right now, you can probably …” Who can wait?

KE:                   Wait to prepare for DITA 2.0, Sarah, or probably don’t need to go to DITA 2.0?

SO:                   More like, “This is going to be lower priority for you,” for whatever reason. Who is that person where you would say there’s not a lot here that’s going to be urgent.

KE:                   Well, I think if your company is offering content in DITA 1.2 or 1.3, and everything is working just fine for you. You’re not experiencing any difficulties with hazard statements, you’re not trying to do filtering on bookmaps. If you’re not experiencing any problems.

SO:                   Do you have any other big picture advice for people that are thinking about this? Anything that we haven’t covered that people should consider or know or think about?

KE:                   Well, I do have one thing I’ll add, you asked who I thought would really benefit from DITA 2.0. And I think companies, if you’re using the troubleshooting topic, one of the key things added in DITA 2.0 is we added structured elements for providing diagnostic information. So if you’ve been shoehorning diagnostic information into troubleshooting topics, now with DITA 2.0 you’re going to have a good semantic place to put that content.

SO:                   Oh, that’s good news.

KE:                   So that’s another area that folks will really get to see some benefit.

SO:                   Okay. Well, Kris, I really appreciate your time today and sharing all your hard-earned wisdom and knowledge about what’s coming up as the expert. And I think with that, I’m going to close it out. As I said, I will leave some additional DITA 2.0 resources in the show notes so that you can, you, the listener, can do your research and figure out where this is going. And we will make sure that we have some possible way of contacting Kris, if you have any inquiries about the DITA 2.0 committee and those kinds of things.

SO:                   And with that, thank you for listening to The Content Strategy Experts podcast brought to you by Scriptorium. For more information, visit or check the show notes for relevant links.