Full transcript of LearningDITA podcast

00:01 Gretyl Kinsey: Welcome to the Content Strategy Experts podcast brought to you by Scriptorium. In episode seven, we discussed the Learning DITA Project.

00:11 GK: Welcome to the Content Strategy Experts podcast. I’m Gretyl Kinsey.

00:14 Alan Pringle: And I’m Alan Pringle.

00:16 GK: And today we’re going to be talking all about learningdita.com and the various adventures in creating this resource.

00:25 AP: And misadventures.

00:26 GK: And misadventures, in creating this resource and bringing it to everyone. So just briefly, for those of you who are unfamiliar, DITA is the Darwin Information Typing Architecture. It is an XML standard that’s widely used in technical communication.

00:43 AP: So, Gretyl, tell everybody what the Learning DITA project is and how it came to be.

00:49 GK: Learning DITA is a free eLearning resource that helps those who need to get started with DITA to have hands-on experience and really learn how to use it for the first time. We’ve got several courses that mix background and conceptual information with a lot of hands-on code examples, and also with supplemental resources like videos and presentations and reading that you can do to learn more about DITA.

01:20 AP: What kind of subjects are covered… ‘Cause DITA is pretty expansive, so how does the content break all the facets of DITA down?

01:30 GK: We started with just a general introduction, and that’s always a great place to begin for those who are really unfamiliar with DITA or who have to start using it for the first time. And then from there, we went on to a series of DITA authoring courses so that people could learn how to create DITA content, and also how to put it together into different file collections and maps. We’ve covered reuse which is something a lot of people use DITA for. It’s one of the biggest benefits that DITA can buy you, so we wanted to cover both some beginner reuse techniques as well as some more advanced ones. And most recently, we have added a course that gets into basic publishing with the DITA Open Toolkit.

02:20 AP: And what’s the DITA Open Toolkit, just to let folks know?

02:22 GK: It’s basically a collection of files that transforms DITA content into outputs like PDF or HTML. And I wanna ask you now how Learning DITA got its start and what all was involved in getting it off the ground?

02:43 AP: Part of it is because we do a lot of DITA implementations. We realize there is really a need out there to get people basic training on what DITA is, how it works, and how all the components work, much like you just talked about, everything from basic use to how do you publish, the kinds of things that are covered in the various courses. And really from a business point of view, there are two primary reasons that come to my mind as why we started this, the first one being people need the education. And having people knowledgeable about DITA, when we go into a company, even if it’s just someone who’s taken these basic courses, it makes the implementation easier. So there was goodness for us in that.

03:37 AP: And it also helps the industry as a whole really, because all of the vendors who make the authoring tools, who make the component content management systems, and all the other infrastructure out there for DITA, having people who are knowledgeable about DITA and then evaluating the tools, it really cuts their sales cycle. It certainly cuts our sales cycle. Yes, this is Scriptorium’s gift to the DITA community, [chuckle] if you will, but there is a lot of goodness for us in it too and I don’t wanna act like there’s not, because with people being more educated about DITA, it makes our sales cycle and implementations a lot better and more streamlined.

04:23 GK: I agree. I’ve seen several cases where rather than having to provide training to a customer of ours and start at the very 101 level with DITA, we’ll recommend to go on Learning DITA first and then we can jump more into their specific needs. So if they’re doing specialization, if they are doing anything different or specific to them, if they have this foundation from Learning DITA, it makes their training go a lot more smoothly and helps save them costs as well.

04:58 AP: I was gonna say, there is a financial component to that for them as well because they’re not paying a vendor or us to give them 101 level of training on the content or on DITA, period, that does help really cut their cost too. You’re right.

05:16 GK: Yes. And then aside from companies, I’ve also seen a lot of people, like students start to use it independently, and so that’s good because eventually the more people who are knowledgeable about DITA and understand how to use it, the more general business it will create in the community. So it’s been a really interesting and helpful thing that, I think, we’ve started. I wanted to also ask you about some of the issues that you’ve run into when it comes to creating the site and, as you said earlier, some of the adventures and mis-adventures we ran into.

05:57 AP: The site is based on WordPress, and we picked WordPress because folks at Scriptorium, myself in particular, was very familiar with setting up a WordPress site and maintaining it, ’cause I’ve been an admin for the Scriptorium site, scriptorium.com, and a few other sites that we have. So we had this knowledge of WordPress, so it made sense to us to try and keep the learningdita.com site also in WordPress.

06:26 GK: Absolutely.

06:27 AP: Yeah. So what we did is we then started looking around at learning management systems that were WordPress add-ons, and we found one. And the system on learningdita.com is WordPress with the LearnDash CMS added on. If you want details on LearnDash, you can go check them out. They’re at learndash.com, and what we’ve done to make a long, boring, technical story short as possible, we had a consultant here, Simon Bate. He has written a transformation process that transforms the DITA XML, the source content, into WordPress-compatible XML that we basically suck into WordPress. And after that, there’s about maybe 30 minutes or an hour of some manual touching up he has to do.

07:19 AP: For those of you who haven’t seen the site, there are quizzes associated with all the lessons. So, you do a lesson and then you a take a quiz. Part of the manual work, really the bulk of the manual work, that happens to get the site into WordPress is to basically hook up the questions to the correct lesson. I would say maybe down the road, if this really gets to be where we’re publishing a course every two weeks or something, we may look into whether or not we need to automate that last bit of hooking up the questions to the correct lesson. But right now it doesn’t make business sense for us to do it, so we’re not.

08:02 GK: That’s an interesting point you bring up about if we ever get to publishing a course every two weeks. That brings me into the next thing I wanted to talk about, which is different ways that you can participate in Learning DITA. And, in particular, for getting more courses out there, one option we have is participating as a contributor. We have had some contributed content before. In particular, our reuse courses have material contributed by easyDITA. We’ve also got videos that were contributed by Sharon Burton. And we have some presentations that were contributed by Pam Noreault. So we’ve got a lot of really great things that people in the community, once they see the Learning DITA site and they’ve seen the project, started going, “Oh, I have something that I can submit to this.” So, Alan, what are some other ways that people might contribute, if they’re interested?

09:03 AP: We do have corporate sponsors for the site. So, some of the vendors who make the authoring tools and the component content management systems, they have offered to pay stipends to us and help us defray the cost of putting the content together. So, that’s been very helpful, too, and really appreciate the sponsors stepping up to help us pay for this, because there are costs associated with putting this site together. So we really appreciate the volunteers giving their time, because we know there’s lots of other things you could be doing in this world than writing Learning DITA content. And we thank the sponsors for helping us out to defray the cost of putting the site together.

09:46 GK: And another way that we’ve had more recently some participation in Learning DITA is with translations.

09:54 AP: Yes.

09:56 GK: So, right now, we have the original Learning DITA Project is in English. We had our first translation into German, and that was done by parson AG.

10:05 AP: Parson in Germany, right.

10:07 GK: And then more recently, we’ve had learningdita.cn, which is the Chinese translation, and that was put together by the Shanghai Association of Technical Communicators, and that just went live a couple of weeks ago. And we’ve got a lot of interest in other languages as well, including Japanese, Russian and Dutch. And so, if there are any languages that anyone wants to see, people can email us, or go on GitHub and submit ideas there. But we are really excited we’ve been able to start expanding this project outside of just the English community.

10:48 AP: And you just mentioned GitHub, and we probably need to explain what GitHub is and what we do with it for this project, so I’m gonna turn that over to you and let you explain that.

10:57 GK: Yeah, absolutely. So, I mentioned that Learning DITA is free and it’s also open source, so we have a GitHub repository where you can submit all kinds of things from course ideas to courses themselves, resources that we talked about, and also ideas about translated content, and we’re going to add, at the end of this, a link to our GitHub repository where we also have a course roadmap. You can see all of the source code in all of the courses. You can get to all of that material in its original DITA files, and download it and take a look and…

11:39 AP: You can use it yourself, too.

11:40 GK: Yeah. You can upload things that you’d like to contribute to the project. It really helps transform it from a Scriptorium only project into a completely community-based project.

11:53 AP: Sure. So, if you need an example, in particular, of the specialization of DITA, there are some basically custom elements in the DITA that are specifically for learning and training content. We based these source files for learningdita.com on that specialization, on those custom elements, and if you are especially considering using DITA content for training content, you could go to the GitHub repository and, like Gretyl said, she’ll put a link in the program notes so you’ll know where to find it. You can go online and you can download those files, and it really shows you how the learning and training specialization can be used in real life, because we set that up using the specialization and then that is what we use to transform it into the WordPress stuff, so it’s a real live example of how it really can work. And, plus, being in GitHub, which is reachable across the web, it’s a free open source thing itself, it helps us draw more people into this and see DITA in action. And the more people that see it being used in real life, I think it gives it a leg up, it makes it more real to people when they can see a real life application.

13:15 GK: Exactly. It goes from something that’s intimidating or difficult to use to something where they can say, “Oh here’s an actual example of it, and I can take a look at it and study it.”

13:27 AP: Yeah. And to me, having not just an abstract example is something that helps with learning anything; it doesn’t matter what it is. So if you’re wondering, “Hey, would this DITA thing work for my training content,” go to the GitHub link, take a look at the files and you can get an idea of how that structure can support all the different kinds of things in learning, and that’s everything from concepts, to lessons, to quizzes, all sorts. The specialization can handle a lot of different things, and we’ve thrown a lot of different content types at it, and so far it’s worked pretty well for us.

14:10 GK: Yes, it really has. And it’s been a good resource as well. As I was mentioning at first, for people like our customers, or just people in the community learning DITA independently, or students, to be able to go to this resource and see some DITA in action, that maybe was not the easiest thing to do before.

14:31 AP: Yeah. And we’ve talked about all this good stuff with the site, and we probably should tell you it wasn’t a completely smooth road to get where we are. There were some bumps along the way, and we’re gonna share some of those warts-and-all with you now. [chuckle] So, what are some of the things that you remember that we had to address and fix along the way?

14:52 GK: Well, I know that when we were first developing the courses, we had to come up with a standard of consistency for how each course was going to be. And, of course, that’s changed a little bit organically over time, but I know one of the big issues was when we were doing, I think it was our second course, it was our first course on authoring, we realized last minute that we had some hands-on examples but we didn’t have any independent activities. So then we all got into a huge rush to add that at the end, but I think it’s been one of the most useful things for our students, to have an on-your-own DITA exercise that they can do and put together.

15:38 GK: But it’s things like that, when you’re first carving out your own path with how you want to do these courses, it’s figuring out, “Okay, how are we going to present this? What kinds of resources are we going to include? How are we going to structure all of our courses in general going forward?” And that’s, I think, been one of the biggest challenges, especially as we move into more advanced topics, is where something like an authoring course structure doesn’t really work anymore, how do we keep the courses consistent and engaging, and make sure they’re covering everything they need to cover.

16:20 AP: And one other thing that we learned early on, we had it set up where you had to complete one course to then do another because we had a very specific sequence in mind from this is the most basic, this is getting a little more specific, and so on, so we wanted to guide people by making courses prerequisites. And our intentions were good, but, [chuckle] however, we had several people point out, “Well, what if I already know the stuff in these early courses and I wanna jump in right in, say, the third or fourth course instead of starting at number one?” And that really… We had enough, I guess, pushback on that where I realized, “You know what, they’re right.” And so we chatted amongst ourselves and we decided to basically take away the prerequisites.

17:17 AP: So, we still recommend, at the beginning of a course, “You need to know this stuff that’s presented in these courses, and then you’ll be ready to take this one,” but we don’t enforce it, you don’t have to do it in that specific order. You can jump in at any course you want without having to go back and do the other stuff. And I think that actually may have opened the site up even more because we weren’t forcing people to learn or review stuff that they already knew.

17:47 GK: And I think it definitely helps on the business side because, when we’ve got clients of ours who may already have a foundation in DITA but they may need to just start with advanced reuse or…

18:00 AP: That’s a good point. Right.

18:01 GK: Jump in somewhere with publishing instead of starting all the way back at the beginning where you’re saying, “Here’s what DITA is.” If they can just start wherever that’s relevant for them, then that helps us be able to get more people using the site and then passing along that information to others.

18:20 AP: Yeah. And another problematic area that we discovered is when parson announced they were interested in doing a German version of the site.

18:31 GK: Yes.

18:33 AP: It’s guaranteed, when you translate content, you are going to find errors in the source, things that are not technically correct. And while the folks at parson were translating our content, they actually found some errors in it. This is stuff we had already published, by the way.

18:47 GK: Yes. [laughter] And we go through very, very stringent rounds of editing where three or four people will review each course before it goes live. But as Alan said, when you translate, that’s when you really find the nitpicky stuff that maybe three or four people could still miss.

19:05 AP: Right. And so it was basically… In addition to them doing their work and getting their site ready, they were basically… It was a QA process for our content.

19:15 GK: Yes.

19:16 AP: As painful it is for me to admit that, it was, and it really shouldn’t have been. Another thing that we did not do or did not really think about… Gretyl you mentioned earlier how we were finding our way and feeling our way, trying to figure out how to put these courses together.

19:32 GK: Exactly.

19:33 AP: We were not thinking about localization when we put these courses together. [chuckle] We were just trying to get something together and out the door, which sounds terrible, but it’s real, and I’m sure a lot of other people out there have faced this in other projects. We were not thinking about, for example, how a lot of the sample files and the exercises, we reuse a lot of that content. We didn’t necessarily set that up very well.

20:00 GK: No, we didn’t.

20:00 AP: And we did not communicate that very well.

20:03 GK: And we didn’t even follow our own reuse best practices that we tell people to do in the reuse courses.

20:09 AP: No. Yeah. So not only did we… We did not practice what we preached, we did not follow localization guidelines that we outlined in an earlier podcast on localization strategy. So we taught ourselves some things or, I should say, parson helped teach us a few things that we realized we did not do as well. And there’s another angle here, too. When you’re working with a lot of different people and volunteers, it can be hard to get everything absolutely 100% right. And that is something you just have to deal with and you’re gonna have to expect. And there was a little element of that in this as well.

20:49 AP: Doesn’t get us off the hook, but it very much plays into this. But I did a presentation at TC World in Germany last year with Tina Meissner of parson. And we’ll put a link to the presentation slides and SlideShare in the show notes so you can see what we went through. Tina and I basically did a walkthrough, “This is how we set up the English source stuff. This is what they did to get the German site running, things that we found that didn’t go very well, and what we’re gonna do to fix that going forward.” So basically it focuses on how we use a lot of different open source and free tools to get this up and running. So even if you’re not into DITA, I think it would be worthwhile to take a look at the slides just so you can see basically how we made decisions, business decisions, why we picked these tools and so on. So we’ll put that in the show notes for you.

21:45 GK: And that’s a very good point especially, Alan, as you were saying, about how we were finding our way. And when you have a project that’s not only an open source community resource that lots of people are participating in, but you also are starting something new and you don’t know how it’s going to go, that’s a recipe for not using best practices because there’s always that point where you say, “Okay, now that this is becoming successful and we are going to continue it, now we can really establish more rules and best practices.” But in the beginning it makes sense that not all of that would be established up front, because it really was an experiment at first.

22:32 AP: It was, and we finally found our way. And now that we have the Chinese version, the German version, and some other language versions in the works, we have to get it right or get it repeatable. We’re always preaching about repeatable processes in content strategy. This is no different, but I think it’s a little more complex because we are dealing with volunteers, we are dealing with multiple languages now. So we have a lot of things we have to deal with, too, and I think we’re teaching ourselves some lessons about how best to really help our clients based on what we’ve learned doing the site.

23:14 GK: Absolutely. It’s Learning DITA for the community, [laughter] but it’s a learning project for us in a whole new way. And I think it’s been really beneficial not only to us but to everyone who’s used it. At this point, we have over 3,000 subscribers.

23:31 AP: As of last week, which is great.

23:33 GK: And we’ve had so much great feedback from people who’ve said it’s helped them, so we’re really excited about the direction that it’s gone so far and where it can go in the future.

23:45 AP: Yeah. And, please, even if you’re only mildly interested in DITA, check out the site just from a technical point of view. It’s learningdita.com. And then there’s learningdita.de, and learningdita.cn. And I should stress that we are not managing any site but the English. I do not wanna diminish those folks’ contributions to this because they have done a tremendous amount of work to get this up and running, and we cannot thank them enough for doing that and running with what we did. We really appreciate it.

24:21 GK: And we appreciate all of you who have taken courses or told people about the site or contributed material and who’ve helped the project grow.

24:31 AP: Yeah. And it’s gonna continue to grow. We’re working on another course right now. And if you have an idea for a course, or you see something in there that is not as good as you would like it to be, let us know. There is a contact form on the Learning DITA site, please use it. All the folks here at Scriptorium, we will see that content and we do answer those questions. We do. We very much pay attention to the feedback to make stuff better.

24:58 GK: All right. Well, thank you, Alan…

25:00 AP: Thank you Gretyl.

25:00 GK: For this great discussion and, yes, everyone, please check out learningdita.com, and the other sites in Chinese and German as well.

25:09 AP: Yes. Thank you, everybody. Bye.

25:11 GK: Thank you. Bye.

25:13 GK: Thank you 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.