Skip to main content
February 3, 2020

DITA projects with a scaled approach

In episode 69 of The Content Strategy Experts podcast, Bill Swallow and Stephani Clark of Jorsek talk about using a scaled approach with DITA projects.

“The desktop publishing and single user tools are always going to have a much lower price tag than a DITA CCMS will, but there’s a trade off for what you’re getting.”

—Stephani Clark

Related links:

Twitter handles:


Bill Swallow:     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 this episode we talk with Stephani Clark of Jorsek about using a scaled approach with DITA projects.

BS:     Hi, everyone, I’m Bill Swallow.

Stephani Clark:     And hi, I’m Stephani Clark

BS:     And we’re going to talk a bit about a scaled approach to DITA projects. So Stephani, what would you say is the best way to get started with a DITA project without a huge investment upfront?

SC:     Well, I think there are lots of ways that you can get started with a DITA project without a huge investment up front. And I think there’s kind of a misconception that DITA is for these large enterprises. And if you’re anything smaller than that, then you probably can’t benefit from it. But the benefits are there regardless of what size organization, it’s just deciding how you’re going to invest if you wanted to move into a DITA environment. And so I think one thing to understand is that there’s always some investment, but I think that there is an opportunity to decide if that investment is going to be purely monetary or if you want to invest some time.

SC:     And there’s a lot of ways now to get started with DITA without the monetary investment that you can use best practices, reasonable tools, approaches to content conversion or publishing, self-education. There’s a lot of resources out there. And so I think that’s something that I want to kind of explore a little more in our conversation today is what can an organization do if they don’t want to go lay out a lot of money to implement DITA? So we can kind of look at each of these items I guess. But what are your thoughts on the best way to overall get started?

BS:     You mentioned that right off the bat that regardless of what your approach is going to be, there’s still going to be a cost associated with it. Do you want to speak a little bit to that?

SC:     Yeah. So let’s look at maybe an example which would be looking at content conversion. So oftentimes when you’re implementing DITA, one of the first steps that you have to take is looking at how are you going to move your content into the DITA structure and get it into a DITA environment. And a lot of companies will do like an engineered conversion and that’s great. I mean those come out really well typically, it’s engineered to your needs and your information model and that’s all fantastic. However, doing an engineered conversion can cost quite a bit of money. And some organizations look at that and see that as an immediate barrier to moving into DITA. But I think if you look at kind of that trade off, it’s going to cost something, it’s either time or money. You can look at easier, do it yourself approaches, whether that’s using a more generic conversion and doing the cleanup or even, I’ve seen companies with smaller sets of content do a lot of copying and pasting to move into a DITA environment.

SC:     So I think that would be maybe an example of, you know, you don’t have to go spend $10,000 on conversion or more, you could spend the hours to get the content cleaned up and in really good shape and get the same results.

BS:     Right. So there’s a mindfulness there between monetary budget and I guess time budget and the amount of resources you have available to get things done.

SC:     Yeah, you do have to have the resources. If you don’t want to spend the money, you need to take into account the time that your team or yourself are going to probably spend on some of the DITA implementation. But once you get rid of that huge price tag that some people see and get scared away by, and you look at it and kind of plan it, I think that that can be a really good approach for smaller teams or smaller organizations that want to start making that move.

BS:     So speaking of price tags, a lot of the tools out there generally come with some degree of sticker shock when you start looking at enterprise content management systems and so forth. Do you have thoughts around those?

SC:     Yeah, I think that is one of the big barriers as well. And one of the reasons a lot of organizations maybe don’t adopt DITA and decide, “Hey, we’re going to use these desktop publishing tools that are already available” or “I can produce a PDF out of Word. I don’t need this more elaborate system.” And so I think it depends on what system you’re looking for. Like the desktop publishing and single user tools are always going to have a much lower price tag than like a DITA CCMS will, but there’s the trade off of what you’re getting.

SC:     But I will say, I don’t want to make this too much about my organization, but one thing we’ve done at Jorsek is we just introduced this year some really low tier options. So people can get started for as little as $15 a month in a DITA CCMS. So there are tools out there that don’t have a six figure price tag that make it a lot more accessible to people and I’m sure there’s others out there as well that have options that are available at at kind of a lower price point

BS:     There’s always the option to use, to really go bare metal and use a source repository such as Git or something like that to at least get yourself started.

SC:     Absolutely. And a lot of organizations are doing that. We’re a DITA CCMS, we’ve seen a lot of prospects coming to us that are already in DITA, got themselves started completely on their own using Oxygen plus Git and then maybe in a few years you decide, “Hey we could probably benefit from a content management system” and it might make more sense at that point.

BS:     So we talked about tools, we talked about content conversion, what about the publishing side?

SC:     So I think publishing is another one of those kind of barriers to entry for DITA. And that is because most DITA publishing is done using the DITA open toolkit, which is an open source publishing engine. It gives you a ton of options. You can publish to any number of different formats, but the kind of caveat there is that there’s usually some initial setup required. So you have to develop a publishing plugin to apply you’re styling and all of your rules for how you want the output to look. The bonus of that is that later on, you have consistent output but the barrier is that yes, there’s an upfront investment, again, whether it’s time or money. If you’re doing it yourself or paying someone to develop it and so you have to look at how you can do that at a reasonable budget.

SC:     But one thing I’ll say is that DITA publishing, what I’ve seen, and Bill, maybe you’ve seen this as well, is that there’s a lot of open source options available to start from and that I’m seeing more options available that aren’t just DITA open toolkit that are maybe easier for people to use. Have you seen the same thing in the industry, Bill?

BS:     I’ve started seeing, yes, some of these, I would say more polished starting points popping up there. I mean the open toolkit is great in that it gives you some initial publishing targets that you can configure. But the catch is that you have to be able to configure them. So you know, if you’re doing PDF you have to know FO or you have to know cascading style sheets for print or for PDF, you need to be able to develop cascading style sheets for HTML. But a lot of tools start coming with some bare bones ones, with some more, I don’t want to call them visual editors, but they’re a good starting point for being able to lay out your output format and then be able to tweak things from there by going into the CSS and fixing things. So there are some options that are starting to creep out there, but they do still require a bit of tweaking to get it just right. Even if it’s just a matter of changing colors and fonts and dropping a logo in, it takes a little bit of time to get up and running, but certainly not as much as trying to configure a bare bones OT plugin on your own.

SC:     Yeah, I think you make a good point that not everyone has the skill set to do it. And so it is important to know that there are some good tools available out there that don’t require that advanced level of skill set. That even the average person could probably get in and do some basic CSS work. We’ve started using Prince XML somewhat, which is CSS for PDF and I know nothing about CSS and yet I can somehow manage to go in there and still like change colors and drop the logo and make it look pretty. So it’s a lower entry point I think then maybe some of the traditional DITA OT publishing options maybe.

BS:     Absolutely. So with regard to getting started, a lot of companies seem to think that it’s going to be a massive undertaking to get things rolling within a company. I know that we’ve seen a lot of companies start doing more of a proof of concept on that end to kind of get the ball rolling. And I was wondering if you’ve seen that as well and what types of, I guess, startup projects you see people implementing.

SC:     We have seen a lot of POCs too and I think a proof of concept, or POC, is a really fantastic way to get started. It helps you build your business case. It helps you validate any assumptions or ideas that you have and you can make it really focused around your core goals for maybe why you’re moving into DITA. So we have a few different POC options that we provide. So we have like two books, like you want to look at reuse and so you just get two pieces of content that are similar in the system and start working on it, to see how much you can reuse, how much easier it is to author and maintain and kind of prove out the points that you want to see. So I love a POC because it’s a great way to prove that a solution will work for you before you make any larger investments in it. What do you typically see with POCs that you guys have been working on?

BS:     Well, a lot of times we do see companies start looking at at least producing one complete deliverable of some kind. So they don’t go head first into converting everything over and focusing on making sure that everything is hooked up and working properly before they start outputting content. So they’ll pick a pet project usually. So if there’s a product development initiative going, especially if there’s a brand new product that’s coming out, usually they’ll align their proof of concept to that. This way, they’re not dealing with legacy content, so they don’t have to deal with conversion as much and they can get in and start authoring the correct way for DITA in the tools for their proof of concept and be able to design the primary. And when I say primary, I mean one, transform or publishing target for that particular deliverable. And most of the times we see that usually being some flavor of HTML.

BS:     This way it can be either served up on the web or provided in a lighter format with a product or what have you. But the key there is to not focus again on everything. If your proof of concept requires you to convert thousands of topics or thousands of documents or thousands of pages of content into DITA first, that’s going to delay getting that proof of concept out in front of people who need to see it to approve a larger investment. So we usually try to help companies identify a small manageable target that they can hit within a reasonable timeframe.

SC:     Yeah, I like that approach of starting from scratch and having a small reasonable project. I’ve also seen with POCs and one of the things I like about it is it’s a really good opportunity for at least like a core team of users to kind of gain experience with DITA, with the tools that they’re going to use and maybe learn some lessons early on in a low risk environment as opposed to trying to do like a full fledged implementation where there’s a lot more risk involved if you start making any mistakes or you have those learning points along the way.

BS:     Absolutely. And that actually brings up another good point and that’s to not try to inject too many bells and whistles into the design of your content upfront. And by that I mean introducing heavy amounts of DITA specialization, which is a customization of the model or using a lot of what I would say more advanced features because usually those require a bit more thought and a bit more set up before you can truly begin authoring your content. Things like using keys to change the context of your content and using a lot of conditional processing. I would shy away from using too much and focus on one goal.

BS:     If that goal is to produce, as you mentioned, two different manuals for a particular set of content, then focus only on that and using those conditions and not all the other bells and whistles that you might be able to use. Keep everything in mind that you want to use going forward, but focus on the key elements that are going to show the people who really will allow you to grow your implementation that “Hey, this thing is going to work for us.”

SC:     Yeah, I think that’s really great advice and it gets you started thinking about how your larger implementation might look and work and what you want to do, but again, keeping it focused for the POC on some simple goals. You kind of brought up one other point though, which is, when you’re getting into DITA, there’s all of these options. You know you can customize it to anything that you want it to be really. What do you suggest for people that are just starting to kind of learn about DITA, in terms of resources to educate themselves on some of these options?

BS:     That’s a good question. Actually. We do have, which is available if you head over there. It’s a 100% free resource for learning about DITA. Up there I believe there are close to maybe 10 or so courses that you can take and there are also several recordings available from past LearningDITA conferences. We do an online conference every February. That’s a great way to get started and get learning about it.

BS:     The other thing that I think is really important is to start taking into account everything you might need going forward. Even if you do have that DITA expertise, taking a strong look at your content and start thinking about how all the bits and pieces need to be able to work in this new environment. Because the goal of really moving to DITA is not so much changing tools and changing the format in which you’re offering, it’s changing everything about how you’re offering in order to deliver something better and to produce something faster. So look at where the inefficiencies are and start thinking about how you want to resolve those or at least identifying what you want to resolve before moving forward. Because the last thing you want to do when you have an investment in changing tools, regardless if you’re going to DITA or anything else, is reinventing the same problems in a new tool set.

SC:     Yeah, I think that’s a great starting point. I recommend LearningDITA to a lot of people and that’s how I got started in DITA surprisingly enough, was through your training courses. So great.

BS:     Glad to hear it’s working.

SC:     And for someone that’s just starting to look at developing a content strategy or what they may or may not need that DITA has to offer, do you have any suggestions for them to get started?

BS:     Well, of course the default answer is please contact us, but no, the best way to go about this is again to look at your content and also understand what the best practices are for authoring in DITA. Generally you want to keep things topic oriented and you want to identify your reusable pieces of information and make sure that you are separating those. Generally you want to do an audit over your entire content set and figure out what needs to be moved over and why it needs to be moved over and which pieces are going to be reused and how, and kind of getting your arms around everything that you had in your content before and what you wish you could have done better with it because chances are there’s a mechanism in DITA that will allow you to do something better with that content.

SC:     Yeah, that’s a great point. And I would just maybe double down on if you’re doing it yourself. I mean, if you’re not using experienced content strategists like Scriptorium folks, I would say always follow best practices. Don’t get too carried away. Try and be a little minimalist in doing just what you need to meet your goals and use the best practices for the industry. And there’s a lot of resources available, whether it’s DITA forums or other options.

BS:     Absolutely. I mean DITA affords you a lot of bells and whistles to do some really smart and interesting things with your content, but you have to be mindful to not try to use them all.

SC:     Yes, if you use them all, it can get a little confusing and complicated quite easily, so.

BS:     Absolutely.

SC:      Alrighty.

BS:     Alright, well thank you Stephani. I think this has been a great little talk.

SC:     Awesome. Thanks for having me Bill. Always nice chatting with you

BS:     And you.

BS:     And 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.