Copyright © Stilo International plc
How to prepare your content
for conversion to DITA
Helen St. Denis | Conversion Services Manager
Stilo International
| LAVACON 2016 LAS VEGAS
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Works closely with Stilo Migrate customers,
helping to analyse their legacy content and
configure appropriate mapping rules
► Provides Migrate customer training and
support
► Helen has helped Migrate customers to
convert tens of thousands of pages of
content to DITA and custom XML
► BA in English from St. Francis Xavier
University in Antigonish, Nova Scotia and
has pursued graduate studies at Queen’s
University in Kingston Ontario
Helen St. DenisConversion Services
Manager
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Legacy content conversion
► IMPORT to CCMS
► 1Million+ pages converted to DITA
| Stilo International (LSE:STL)
<high-performance content processing>
<web-based XML authoring for SMEs>
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
| Our customers
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Word
► FrameMaker
► InDesign
► RoboHelp
► Flare
► AuthorIT
► DocBook
► Confluence
► Ventura
► HTML
► Other
| What source formats are you converting from?
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► What you actually need to do to the
documents you are going to convert,
to get good, usable DITA quickly
► What you probably don’t need to do
► What you may want to do
| What we will talk about
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Content audit
► Identifying redundant content
(other than what you are already reusing)
| What we won’t cover
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► That depends, of course, on two things…
| How much work is this going to be?
What your content
looks like nowWhat you want it to
look like
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► If there were absolutely no cleanup
required, you would already be authoring in
DITA
► If you have a group of documents that
aren’t being actively edited, and just need
to get them into the CMS quickly, then it
may be OK to leave most of the work until
after the conversion
► If you are actively modifying and editing the
documents, it is likely more efficient to do
pre-conversion work during that process,
so that at release time, you can simply
convert and be ready to go
| Pre-conversion vs. post-conversion cleanup
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Topics. Generally these are easy to break out, based on heading
levels. Nothing to do here except decide how many levels to go
down
► Topic types. A few organizations will choose to make everything a
concept, or even just a generic topic; the typing aspect of DITA is not
important. Again, nothing to do
| What do you really, really need to do?
For most, though, it is important to get the topic type right at
conversion time. Cleaning that up after the fact is not fun
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Authoring conventions:
► Tasks begin with gerunds, or “How to”
► Concepts begin with “About”
► References may have titles that are command names, and
begin with lower-case letters
► Paragraph styles: Many already use styles like “procedure
heading” for tasks
► Prefixes in the text: T_, R_, C_ These can be stripped from the
content on conversion. Many people prefer to have their file
names prefixed in this way, so they could be retained there if
desired
| Indicating topic types
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Markers (in FrameMaker)
► Templates (RH)
► Allow conversion to determine based on content of topic
| Indicating topic types (continued)
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Tasks are trickiest
► Only one set of steps allowed
► No sections, stuff before and after steps must be in a specific order
| Data model
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
Widget names
► By selecting the field right of ‘Widget', the name of a widget can be
entered…
► To change the name of a widget:
1. Left-click in the modify-widget field and enter the new name
2. Right-click to confirm
3. Left-click on the widget label, to activate the name change function
4. Left-click on the widget to change the name from
5. Right-click to confirm
6. Middle-click to cancel the pending function
| Example…
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► But the most common way to change a variable name of an existing
dynamic object is:
1. Left-click in the EDIT field, to enable editing mode
2. Left-click on the widget to change the variable from
3. Right-click to confirm
4. Enter or select the new name
5. Left-click on OK to activate the name change
| Bad example…
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Especially important if you will localize
► Some things must not be translated
► Some things will be presented differently in different languages
► You may already have styles for these things, typographical
conventions
► But there may be ambiguities
| Inline elements
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Character level style names. This is workable if you are still
authoring
► Color coding; if the doc is already in its final form it may be faster
just to go through and color code the text according to a legend you
create
| Indicating inline elements
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Tables
► Links
► Variables
► Conditions
► Having all the answers
| Stuff you probably don’t need to worry about
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Are they in a supported format?
► Where will they be stored?
► Do they rely on superimposed callouts?
| Other considerations – Graphics
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Sometimes hard line breaks are used instead of soft, resulting in a
new paragraph where none was intended
► Sometimes, soft line breaks have been used instead of paragraphs,
resulting in run-together text
| Other considerations – paragraph breaks
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► This can often happen with textboxes. Usually a minor issue
► Occasionally can be a significant problem. InDesign documents may
need to be rethreaded
| Other considerations – text in the wrong order
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Html inputs will usually need to be “tidied” to xhtml
► DocBook inputs will need to include a valid doctype
► FrameMaker docs need to be saved out as .mif
► Word docs need to be saved out as docx
► InDesign need to be saved out as IDML
► Might as well delete ToC, LoT, LoF, Index
| Etc…
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
► Probably should
– Indicate desired topic types
– Ensure content fits data model
– If needed, ensure inline semantic elements are identifiable
► Probably don’t need to worry about
– Tables
– Links
– Variables
– Conditions
– Having all requirements finalized
| Summary
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
Questionswww.stilo.com/migrate
THANK YOU!
STILO | HOW TO PREPARE YOUR CONTENT FOR CONVERSION TO DITA
Copyright © Stilo International plc
Free conversion offerSubmit sample document (20-30 pages)
stilo.com/migrate
Real-time content conversion to DITA in the cloud(Webinar recording)
stilo.com/knowdita
| Discover more about Migrate
Migrate Live DemoThursday, November 3, 2016
9:00 AM PST | 12:00 noon EST | 4:00 PM GMT
stilo.com/webinars