Agility and Quality DITA for Three Converted to DITA and ... · Writing content in DITA, using Oxygen XML Editor Using DITA Open Toolkit to generate help and PDFs Using Jenkins for

©2014 Advanced Instructional Systems, Inc. All rights reserved.©2014 Advanced Instructional Systems, Inc. All rights reserved.

DITA for ThreeHow a Small Tech. Comm. Department Converted to DITA and Improved Our Agility and Quality

©2014 Advanced Instructional Systems, Inc. All rights reserved.

About Us

● WebAssign is a flexible and fully customizable online instructional platform

● WebAssign has about 170 employees● Three of us made up the Technical Communications

team:○ Jen Malloy○ Misti Pinter○ Shane Taylor


Where We Were● Writing content in unstructured FrameMaker● Using FrameMaker to generate PDFs● Using RoboHelp to generate online help● Generating 2 Online Helps & 3 PDFs● Publishing about every 2 months


Why Change?


Why Change?Our tools were eating our productivity

● FrameMaker○ Limited content reuse○ Content reorganization was time-consuming ○ PDF production was manual and subject to errors

● RoboHelp○ Help production was manual○ Help ALWAYS had build errors○ Help QA & fixes generally took a full day each time


Why Change?

● We had varying degrees of DITA experience from previous jobs

● We knew there was a better way


Converting the Content


Conversion

● Already used topic-based paradigm● Roughly 500-600 PDF pages of content● Conversion from mark-up to clean-up took

roughly 4 weeks


Preparing the Content

● Apply styles in FrameMaker● Insert filename markers on headings

○ Filename should identify file type● Map FrameMaker styles in Mif2Go

○ Used the trial period to test mapping


Converting the Content

● Used Mif2Go to transform FrameMaker to HTML○ Markup might be valid but not correct

● Used DITA-OT to convert HTML to DITA


Cleaning the Content

● Markup might be valid but not correct● Fix a repetitive error by remapping content in

Mif2Go● Fix some kinds of errors with regular

expression searches of converted files


Post Conversion

● Create bookmaps and ditavals● Edit locally using Oxygen Editor ● Set up a Git repo for version control (no

CMS)● Builds were initially done via Oxygen


Publishing DITA Content


Builds

● Builds use○ XSLT for online help○ XSL-FO for PDF

● DITA Editors come with packaged transforms○ Initially we used Oxygen Help Transform

● Specialized DITA Open Toolkit transformations


Builds

● Created Ant build files● Wanted builds to kick off when content

changed


Builds

Use XSL for log readability in the browser


Creating PDFs


Creating PDFs

We spent a couple months working to match the previous PDF formatting from FrameMaker

● Negotiate formatting with stakeholders beforehand● Basic formatting changes can be made easily with

Jarno Elovirta's plugin generator● Use Apache FOP


Creating Helps


Creating Helps

To start with, we used Oxygen's (v11) webhelp● Frames-based● Used CSS to customize● Search was...not worse


Where We Are Now

● Custom HTML5 help application using AJAX

● Google Custom Search Engine


Where We Are NowWe are:● Writing content in DITA, using Oxygen XML Editor● Using DITA Open Toolkit to generate help and PDFs● Using Jenkins for continuous integration builds● Publishing 7 Online Help Systems & 3 PDFs

(1143 topics)● Publishing about every month


Resources


Resources● DITA Open Toolkit (http://dita-ot.github.io/)

● Git (http://git-scm.com/)

● GitBox (http://www.gitboxapp.com/)

● Google Custom Search (https://www.google.com/cse/all)

● Jarno Elovirta's Plugin Generator (http://dita-generator-hrd.appspot.com/)

● MIF2Go (http://mif2go.com/)

● Oxygen XML Editor (http://www.oxygenxml.com/)

http://dita-ot.github.io/

http://git-scm.com/

http://www.gitboxapp.com/

https://www.google.com/cse/all

http://dita-generator-hrd.appspot.com/

http://mif2go.com/

http://www.oxygenxml.com/


ThankYou1791 Varsity Drive, Suite 200Raleigh, NC 27606

Tel: 800.955.8275 or 919.829.8181Fax: 919.829.1516www.webassign.net

Agility and Quality DITA for Three Converted to DITA and ... · Writing content in DITA, using Oxygen XML Editor Using DITA Open Toolkit to generate help and PDFs Using Jenkins for

Documents