LavaCon 2017 - Implementing a Customer Driven Transition to DITA - Part 1

Implementing a Customer-driven
Transition to DITA Content
A Step-by-Step Journey to Success
www.thecontentera.com 111/2/2017

President –
Director Tech Comm –
SVP Global Operations –
Founder/CEO –
Founder/CEO - Tom Aldous
Email: tom.aldous@thecontentera.com
Blog: www.tmaldous.com
YouTube: http://bit.ly/TheContentEra_YouTube
www.thecontentera.com 2 11/2/2017
- 30 Years in Technical Communication
- XML Expert
- Certified FrameMaker Expert
- Structured Authoring Wizard
- DITA Specialization Expert
- Content Strategist
- Industry Influencer

About Us
 We love solving problems in real-world conditions.
 We help you identify the tools and strategies that work best for your
content. Then, we train you to use them effectively.
 We can help you with structured content creation and management.
 Our knowledge of content tools, markup languages,
scripting/automation, and best practices reduces cycle time and
increases efficiency.
 We know your existing content is valuable: many of our projects
involve conversions to structured content and between XML
standards.

Today’s goal and how we can help
 Demonstrate one client’s unique issues and showcase the TCE
solution.
 Every company has a unique set of requirements and issues. Cookie-
cutter solutions cannot address unique content.
 Existing content rarely translates directly to the DITA standard -
creative solutions built with XSLT, read-write rules and scripts
prepare your content for the transition.
 If you do not need to convert content and your solution is simple,
we can train you to modify templates to extend out-of-box
solutions.

Challenges
 Categorize topics as concept, reference, or
task upon conversion.
 Minimize content rework before conversion
(such as untangling conceptual information
from procedures).
 Retain some formatting items, such
as table alignment.
 Retain some unstructured FrameMaker features
in early phases to support a phased transition.
 Address legacy content that inherently includes overrides,
formatting tags, cross-reference issues,
and other difficult-to-find remnants.
 Retain cross-references over topic chunking.
 Automate process as much as possible to avoid disruption
 Deliver a user-friendly publishing solution that allows import of
variables and conditions

Creative solutions for unique content
Structured Application
Scripts
Read/Write Rules
Stylesheets

Categorize topics
 How we did it:
 Apply unique paragraph tag only to the headings of reference and
conceptual information
 Creative handling of the conversion table to convert every topic to the
strictest topic type: task
 Stylesheet to correctly categorize topics into concepts, references, and
tasks

Minimize content rework before conversion
 Some “topics” contain multiple
information types in the unstructured
environment
 How we did it:
 Convert procedures by nesting tasks to
generate valid XML upon conversion
 Let each authoring team define the
schedules for “untangling” content,
such as removing conceptual information
from procedures

Retain some formatting items
 Some formatting items were
important to retain, such as table
alignment and styles
 How we did it:
 We retained table alignment by
wrapping the table element in a
p element, and using the p element
to drive alignment

Retain some unstructured FM features
 Since our approach is a phased one, we need to retain variables and
conditional text in the early phases.
 How we did it:
 Use FrameMaker conditions as in
unstructured FrameMaker
 Wrap variables in ph element
and continue to use the FrameMaker
Variables dialog as in unstructured
FrameMaker
 Publishing solution imports variables
and conditions across the publication

Address legacy content: character formats
 Character formats are sometimes incorrectly applied (do not use
character format tags)
 How we did it:
 Created script to search for incorrectly applied character formats and
capture these in the conversion table

Address legacy content: formatting tags
 Many paragraph tags in the unstructured template are used solely
for formatting, and therefore need to be deleted
 How we did it:
 Created script to search for and delete formatting paragraph tags

Address legacy content: X-ref issues
 Common problems with cross-references in legacy content include:
 Multiple paragraphs with identical X-Ref marker. This occurs because
new chapters were created from existing chapters (h1 X-Ref marker
duplicated when new chapter created).
 Paragraphs with more than one X-Ref marker. This occurs frequently
because index markers are mistakenly inserted as X-Ref markers.
 How we did it:
 Created script to add the chapter name as the prefix to every cross-
reference marker. This ensures X-Ref markers are unique.
 Created script to check for and fix paragraphs with multiple X-Ref
markers.

Address legacy content: graphics
 Many legacy graphics include
multiple (and sometimes
hidden) frames
 How we did it:
 Created script to check every
anchored frame for composite
graphics

Retain X-Refs over topic chunking
 How we did it:
 Merge book and then fix resulting unresolved cross-references
 Fix legacy cross-reference issues
 Created script to generate the correct link format for cross-references
(append idref to the href following # symbol)

Automate process
 How we did it:
 Created a user-friendly workflow by:
 Allowing authors to run scripts from custom built menu in FrameMaker
 Using different structured applications during conversion and authoring
 Using Read/Write rules to roundtrip XML
 Using stylesheets to adjust structure where necessary

Publishing solution
 How we did it:
 Leveraged and extended the out-of-the-box FrameMaker publishing
solution
 Used ditafm-output.ini file to define PDF publishing parameters
 Built FM book from ditamap
 Created script to import variables and conditional text settings from a
predefined “control” file (saved in the same folder as the ditamap)
 Generated book also used to output responsive HTML5 (using the
FrameMaker Publish dialog)

LavaCon 2017 - Implementing a Customer Driven Transition to DITA - Part 1

More Related Content

Similar to LavaCon 2017 - Implementing a Customer Driven Transition to DITA - Part 1 (20)

More from Jack Molisani (20)

Recently uploaded (20)

LavaCon 2017 - Implementing a Customer Driven Transition to DITA - Part 1