Today I’ll be talking about my recent experience of using DITA. My history with DITA is limited; I have much more experience using plain ol’ xml than DITA! However I did complete a few short (and very basic) projects using DITA. Some authoring tools I’ve used in the past are Frame Maker and RoboHelp. I’ve started using a CCMS tool and this post focuses on me attempting to create a custom HTML5 plugin.
After months of deliberation, I decided to look for a new job. To cut a very long story short, I found somewhere new and started in October. I’m now a few weeks in and the new challenges are taking shape.
One of my new projects is to help implement a new CCMS (Component Content Management System) the main goals being:
- To be able to output content in HTML5 format – For use on the web.
- To create content that adheres to a topic based authoring structure – A modern way of writing content so that is it smaller and easier to digest by the reader, Mark Baker’s Every Page is Page One goes into more detail on topic based authoring.
- To implement single sourcing publishing – Create content once, edit it once, publish to many formats. It makes content extremely easy to reuse. Feeds into topic based writing too.
So we’re working with a few 3rd parties, namely to help with the transition and content strategy. However, the IT tech in me wants to know how all this is working and how it’s going to be put together. After all, if there is an expectation for me and my team to handle this going forwards, I need to know exactly what is involved. I see too many companies invest in projects then have overheads attached to 3rd parties for maintenance. Okay, maybe that’s where we will end up going, but I need to understand the inner workings to be able to make that decision. Also I hate spending money on externals if we can train skills in house. Anyway..
After looking at the new CCMS tool, I decided to go back to the core of DITA and take a look at the DITA Open Toolkit (DITA-OT). The CCMS tool at this moment in time, doesn’t appear to automatically create HTML5 output that is responsive, or with any styling attached. When you think of tools like Frame Maker and RoboHelp there is an element of style that these tools allow you to add – in an extremely easy and customisation way. However, I am starting to wondering if this CCMS tool is meant to be used purely as a CCMS tool, even though it has also been advertised as a authoring tool. The authoring GUI is very good and the editors are going to enjoy using it much more than the previous tool, however that doesn’t help me with my issue of generating the output!
The CCMS tool allows you to import DITA-OT plugins, so I decided to create one for myself to see what I could do with it. The first issue, my work laptop – I’m not used to being a “normal” user (without local admin access) and I have to make requests to IT to install anything. So I’ve had to do all my testing at home on my own machine for now. I’m using DITA-OT version 3.1.2.
I started following a guide on the DITA OT website called Bundling CSS in a custom HTML plug-in which has been somewhat helpful (note: there is an up to date document for version 3.1.2 inside the DITA-OT zip in the doc folder). However following the step by step guide didn’t work. There also doesn’t seem to be that much help around online which is so frustrating! I decided to tinker and thought I’d share my main discovery points here.
You can install your plugin by running the following command:
<DITA-OT dir>bin\dita –install
The instructions at first confused me a bit and I kept trying to run bin\dita –install custom.html5.css it was only after reading the instructions again I thought to try running it without the plugin name at the end. Running this picked up my new plugin which essentially allows the transformation tool to use it to generate new output. I then ran:
<DITA-OT dir>bin\dita –input=myfilename.xml –format=html5-custom-css
(Note: Yes, I didn’t run this on a .ditamap, I just wanted to run it on a single .xml file first.)
Now I haven’t configured the entire DITA OT yet, so I may be missing a crucial step. When the transformation completed, it generated a set of new files in the following location (note: My toolkit is installed in the c:\ drive).
Then inside this were two folders:
The changes I made to the plugin were really simple – I just wanted to override the original css and change the body colour to red, as per the example given on the DITA OT website.
The HTML5 output file was sitting in the dita-ot.3.1.2 folder, however when I ran the file and checked the output in Chrome, the body text was still black. After using F12 to inspect the page, I realised that the page was expecting to find the css folder within the dita-ot.3.1.2 folder. I moved the css folder into the dita-ot.3.1.2 folder and BRAVO! body text was red.
I feel like I’ve made a step towards building my own custom DITA html5 plugin, my next step is to see if I can get this to work with the new CCMS. I also want to investigate the use of web frameworks, namely bootstrap, but at the moment I have concerns about how this will work…more investigation is needed.
As a side note, another research area for me is the Learning and Training specialization of DITA. But that’s a story for another time.
If you are looking for an introduction into DITA I would recommend the following training by Cherryleaf, DITA Fundamentals, it’s part of the Advanced Technical Communication training course. It is a paid for subscription, but you can cancel at anytime. I found it to be very slightly out of date as it’s based on an old version of the plugin, but it gives you a good overview of the DITA architecture.
You can also find lots of free resources online, especially at Scriptorium.
Baker, M. (2013). Every Page is Page One. XML Press, California.