23 minutes | Mar 9th 2020

Getting started with DITA (podcast, part 1)

In episode 71 of The Content Strategy Experts Podcast, Gretyl Kinsey and Barbara Green of ACS Technologies talk about getting started with DITA. “We ran the conversion and got the content in DITA. It wasn’t structured the way it would be if you had started writing in DITA from the beginning. If I ever had another project, I would know to really take that into consideration.” —Barbara Green Related links: Managing DITA projects: Five keys to success Twitter handles: @gretylkinsey Transcript:  Gretyl Kinsey:     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 about getting started with DITA and taking the next steps forward with special guest Barbara Green of ACS Technologies. This is part one of a two-part podcast. GK:     Hello and welcome to the podcast. I’m Gretyl Kinsey. Barbara Green:     And I’m Barbara Green. GK:     And today we’re going to talk about a case study with the project that Scriptorium did with ACS Technologies, started a few years ago and it’s still ongoing, about getting the company started with DITA. So first thing that I want to ask you, Barbara, is to just give us a brief overview of the company. Tell us what ACS Technologies does. BG:     Okay, well, ACS Technologies has been in the business for about 40 years. We develop software solutions primarily for faith based organizations, and our corporate offices are in Florence, South Carolina, but we have distributed teams throughout the country and offices in Greenville and Phoenix as well. GK:     All right, perfect. And when it came to moving into DITA, what were some of the reasons that you wanted to start looking into changing the way that you were developing content? What were the business drivers behind this decision? BG:     Well, we were developing our flagship product at the time, which is called Realm, and it began to grow more complex even though we were still in the early phases. It wasn’t developed as a core product with modules that plugged in depending on the features our customers wanted, but instead features were turned off and on based on packages or experiences that customers required. BG:     And so I guess about three, three and a half years ago, I realized we can’t keep documenting the way we’re doing. In the early stages of that development, writers could add notes here and there to help customers find their paths. But we knew this was not the user experience that we wanted to create and we also knew that the product offering was growing more complex and personalization was on the horizon. We also spent many hours formatting content. BG:     So, right away we had four problems that were identified. We needed to target custom content, we needed to integrate content within the product, we needed better findability for sure. Search was a struggle. We had multiple output types and while we had tried very hard to move just to online, many of our customers still requested PDFs. We also were seeing content reused across various departments more and more and we really could not prove our value because we lacked a cohesive set of content metrics. GK:     Yeah, and I remember when Scriptorium went in and helped assess all of these issues, those were the root cause of all of those were kind of coming from the fact that all of the content was being offered in a Wiki. So, all of the Realm help content was stuck in this silo that made it really difficult to achieve all of those things, especially things like search and reuse and personalization. And so I remember back when we were initially talking about this, that we were looking at all of these problems and DITA seemed like absolutely the logical solution to help solve all of them over time. BG:     Yes, it did. When we had software products that were more modular in orientation, the Wiki worked okay. I’ll say that years ago the Wiki got us online where our help had not been online. So it had a value at the time. But we really outgrew it very fast. GK:     Right. And I think that’s something that we’ve seen in a lot of different organizations where some solution that does help you at one time isn’t scalable in the way that DITA is. And so making that transition makes a lot of sense. So I want to get into talking some about how we actually went about getting everything up and running with DITA and the strategy that we put in place to make that happen. GK:     And the approach that Scriptorium ended up taking with ACS Technologies was what we call a phased approach. So this was determined by a lot of different things including timelines, schedules, budgets, and it also gave us the opportunity to start small at a pilot level and then expand outward. GK:     So, we set up content strategy in phases where each one built off of the previous one and we have pretty much stuck to those phases. The timeline of those has gotten a little off track from what we’d initially planned. Some phases happen more slowly, others have happened more quickly. But we initially outlined these phases and then just started tackling the plan in that order. And so I wanted to talk to you about how that’s gone and we can get into a little bit what those phases involved and how that played out in reality versus what we had initially planned. BG:     Right. Yes, I think no one is more surprised than I that we’ve made it through four of the five phases. GK:     Yes. BG:     It’s like a dream come true, right? GK:     Yeah, absolutely. And so, we really just started phase one. The big push there was just getting the content out of the Wiki and into Dita and so that involved a process of conversion. And so I wanted to just get your take on how that process went and what kinds of things that you wish you had known in hindsight. BG:     Yeah. So, I guess the conversion itself after running several test iterations went very well considering the product we were converting from. The Wiki that we used puts a lot of junk code in the background. So, Lord bless the developer that had to write that for us. One of the big surprises there that we found is every time we had uploaded an image, there was a version of that image in the database. So, that was a lot of fun to try to figure out. GK:     Oh, wow. BG:     Yeah. But we ran the conversion and got the content in DITA. Now it wasn’t structured the way you would if you had started from the beginning writing in DITA and if I ever had another project, I would know better now to really take that into consideration. We’ve talked about, we don’t feel we made a bad decision converting content, but we have sat around the water cooler, so to speak, and talked about, “Hmm, would it have been easier to just start over?” Because we didn’t have a very large set of content at that point. GK:     Yeah. And that’s something that I think all companies have to take into consideration. Is it easier to rewrite or restructure or reorganize your content on the front end before you convert or do it after you convert? And it’s a difficult question, especially when you’ve got such a small set of content. Because the good thing about that is it doesn’t take as much time either way compared to if you had hundreds of thousands of topics. But it’s still a big thing to consider to try and make sure that you take whatever approach is going to be the least amount of stress and time and effort on the people that have to do that work. BG:     Right. And the driving factor for us to convert too was we had been given a timeline and so we felt like if we didn’t convert, there was no way we could meet that timeline. I guess one of my lessons just personally, as an information manager at the time, is push back on timelines. GK:     Yeah. And I think that as content strategists here at Scriptorium, that’s an important thing too, is to be realistic about timelines, because we see that a lot where you’ll have executive pressure to get something done by a certain date, but then you often have to compromise. Do you get it done by this date and maybe it’s not done quite as well? Or in the same way that you would have done it if you had unlimited time? So, you have to find that sweet spot of what’s the right amount of time to do something correctly but still try to meet your deadlines or meet a schedule or not get things behind. And that’s always the challenge that I think companies face with something like this. GK:     But as we know we did get through that phase. And so then phase two was basically an interim phase of using the content in Dita, managing it under source control with Git, and starting to deliver HTML output. Particularly a couple of different variants for different customers. And the main goal of that phase was just basically stay in it until you reached a critical point of needing a component content management system to manage things like workflow and publishing and especially publishing, all these different content variants. GK:     And I think this was the phase that we stayed in a little bit longer than we had initially planned because I think we had planned for that to maybe be six months to a year and that ended up going on longer than we thought. So, I wanted to get your perspective on that phase of the project and how things went. BG:     Yeah, so it did go on longer than we thought it would. It also went on probably longer than it should have from a technical standpoint, but again we’ve gotten through it. One of the lessons learned, and we’ll talk about this more later, is making sure that you have development resources in place. BG:     O
Play Next