Getting started with DITA (podcast, part 1)
Podcast: Play in new window | Download
Subscribe: Apple Podcasts | Spotify | Amazon Music | Email | TuneIn | RSS
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:
Twitter handles:
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: Our designer lead at the time and our developers came up with a front end. It was a single page app for us to publish to and I think they refer to it now as a homegrown system. But our version control was in GitHub and that was a very steep learning curve that occurred at the end of the year. So, with the holidays and everything. It was not that writers can’t learn, they do. Writers everyday learn to use GitHub. But we did not have a pretty front end for GitHub.
BG: We had to learn through command prompts and memorize command lines. I think we didn’t know any better. And so that was very technical. It was a steep learning curve and we were not all there all the time learning at the same rate. So we made a lot of mistakes with GitHub and we’d have to grab a developer and get them to help us figure out what we had done wrong.
BG: Over time that evened out into the next year. But our homegrown system didn’t accommodate the complexity that we were adding on a very regular basis to our content. So, our company began to go through reorganization at that time. We had lots of change and change management. Technologies were changing, dev resources were stretched, writing resources were stretched.
BG: And so sometimes we would make a change, commit it to Git, and we couldn’t publish. And we spent lots of time troubleshooting, would have to pull in development resources, and often those would get escalated. We would be putting SOS signals out to Scriptorium, what we had done wrong. So, it definitely had its hills and valleys. There were weeks that were extremely frustrating and then there were weeks that it went along pretty well. But it was a rough patch. I personally couldn’t wait to get into a CCMS.
GK: Yeah. And I think what you just described with those peaks and valleys and with your homegrown system not being able to accommodate the complexity of the product and its content really embodies that critical point that I mentioned about when it’s the right time to move to a CCMS. And I think that one of the big challenges was that you reach that critical point but then still had to wait a little bit longer to get into a CCMS. And of course with that process, you always have to go through evaluating different options and figure out which is the right system for you, which is the best fit for your business goals and your content.
GK: And so once we finally got the green light to do that, that’s when we moved into that phase. And so now I want to just get into talking about that. So phase three was getting into a CCMS and getting set up where you could have all of the workflow in place and where you could start to deliver more content variants, more of those personalized variants to different segments of your customer base.
BG: Yeah, so we did go through a formal RFP process and that was really a great experience in hindsight. If anyone asked me the single most important piece of advice, I would say, don’t skip it, do it. So we picked our CCMS and for me that was my highest priority in my role, was to do whatever I needed to do to get that stood up, to get workflows in place, working with our vendor. All the little things that you have to do to make it ready for writers to move into. And we talked about moving day, what would be our moving day? We were ready to move into it, but we did have to wait on development resources to make some changes.
BG: Our product, if a user’s in our product and they click the question mark, it takes them straight to the page and help that they need to view. And also our content was being … They needed to get to the right content for the package that they were using for the version.
BG: And again, our complexity was growing. Scriptorium had recommended, we have no more than five versions or filters, variants. We were approaching … It would get to 20 and then 25 and I think we ended up at 36 or 37 variants. So, we had to wait for development to make that switch and then when they made that switch, what we were able to do then is we began authoring and version controlling workflow handled in our CCMS and they pulled our source files down and continued to run them through the DITA Open Toolkit to produce the various help pages. It did take a little bit of development work to get there.
GK: Yeah. And I think that what you’ve mentioned about all those different variants to leads into where that phase with the CCMS bled early into the next phase that was planned, which was for phase four. We had recommended once you get to a certain number of variants, that’s too much to keep publishing all those different outputs. Whether you’re still in Git or in a CCMS, once you get that many variants we recommended that the best way to deliver content was through a dynamic delivery portal.
GK: And what was really interesting was that that came for ACS, right on the heels of getting the CCMS. You got them both right back-to-back and it was an overlap where basically you chose your CCMS and then chose your portal right on the heels of that instead of having a longer phase in the CCMS. And so I want to talk to you about that overlap between those two phases and what led to that decision and how that’s gone so far.
BG: Yes. That old phrase, be careful what you wish for, right? One of the best things that we did was our dev resources. We had some dedicated dev resources that did walk through the RFP process of the CCMS. And during that process, the concept of portals was introduced by more than one of the vendors. So there was a lot of excitement from development to get behind that for our sakes. And I really appreciated that.
BG: And so that led to … Somebody started calculating the number of dev hours they were spending in the current front end we were publishing to and the writing hours that we were wasting troubleshooting the front end. The business case just got made much faster than I anticipated and we purchased the portal.
BG: When I stand here today and think, “Wow, we stood up a CCMS and a portal in the same year.” I can’t even believe it. But we did. And it was a lot of work. But I’m glad in the long run that we did that. Now again, what we ran into is, I believe, that we had underestimated the technology that we needed to have in place in order for the portal to do the best job and I actually had anticipated design resources thanks to … Right now, I can’t remember her name, but someone had said, “Don’t underestimate design resources.” And so we had anticipated that and our UX team just did a fantastic job on the designs for our portal. It’s beautiful.
BG: And so our design was in place but we just didn’t have everything. We didn’t have the dedicated resources we needed from development or the priority. We did eventually get to a place where those things have been put in place and our portal was up several months ago. Technically we could publish to it, but we were also still locked into a situation where we have to publish the old fashioned way, as we call it now.
BG: And we will be doing user testing on it. We can already tell one of the big wins for us right now, builds take an hour and 10 minutes in the old system. They’re published within a minute, you can go out and see the new content that you wrote in the CCMS, pushed through APIs to the portal. It’s so fast. It’s such a time saver.
GK: Yeah. And that makes a really big difference in terms of your time to delivery. So, that’s a really big accomplishment.
BG: Yeah. It’s great. There’ll be some other tweaks and things that we want to make obviously, and we’re sort of now going, “Oh, could we do this? Could we do that?” But yes, it’s going to be great to turn that final switch and do away with the old system.
GK: Yeah. And I think it’s really a good thing to show something like this, which is the ultimate point of your content strategy coming to fruition and you being able to deliver through that portal. Because that was … It’s not the final phase, but it’s a major delivery end point and I think achieving that goal in the timeline that you did, especially considering a lot of the challenges that you faced with reorganization in your company with resources being moved around and things being changed, it’s really I think quite uncommon to see a company stick to the plan that well and achieve the goals within that reasonable of a timeline.
GK: I know that it’s very common for a lot of unexpected things to crop up. Sometimes you have to adapt your strategy and go in a different direction based on circumstances outside of your control. But I think it’s really impressive that ACS Technologies managed to really stick to the plan and has been able to prove the success of it phase by phase even with all of those external challenges.
BG: Yeah, I think it is too. And I would definitely agree with you, caution anyone else that that is a big challenge to do both of those things in the same fiscal year.
GK: And with that, I think we’re going to go ahead and wrap up part one. We will be back with part two in our next episode.
GK: Thank you all for listening to the content strategy experts podcast brought to you by Scriptorium. For more information, visit scriptorium.com or check the show notes for relevant links.
About the author
