©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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Why Change?
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Why Change?
● We had varying degrees of DITA experience from previous jobs
● We knew there was a better way
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Converting the Content
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Conversion
● Already used topic-based paradigm● Roughly 500-600 PDF pages of content● Conversion from mark-up to clean-up took
roughly 4 weeks
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Publishing DITA Content
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Builds
● Created Ant build files● Wanted builds to kick off when content
changed
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Builds
Use XSL for log readability in the browser
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Creating PDFs
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Creating Helps
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Creating Helps
To start with, we used Oxygen's (v11) webhelp● Frames-based● Used CSS to customize● Search was...not worse
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Where We Are Now
● Custom HTML5 help application using AJAX
● Google Custom Search Engine
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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
©2014 Advanced Instructional Systems, Inc. All rights reserved.
Resources
©2014 Advanced Instructional Systems, Inc. All rights reserved.
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/)
©2014 Advanced Instructional Systems, Inc. All rights reserved.
ThankYou1791 Varsity Drive, Suite 200Raleigh, NC 27606
Tel: 800.955.8275 or 919.829.8181Fax: 919.829.1516www.webassign.net