Helen St Denis: How to Prepare your Content for Conversion to DITA

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
► 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. Denis
Conversion Services
Manager

► 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>

| Our customers

► Word
► FrameMaker
► InDesign
► RoboHelp
► Flare
► AuthorIT
► DocBook
► Confluence
► Ventura
► HTML
► PDF
► Other
| What source formats are you converting from?

► 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

► Content audit
► Identifying redundant content
(other than what you are already reusing)
| What we won’t cover

► That depends, of course, on two things…
| How much work is this going to be?
What your content
looks like now
What you want it to
look like

► 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

► 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

► 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

► Markers (in FrameMaker)
► Templates (RH)
► Allow conversion to determine based on content of topic
| Indicating topic types (continued)

► Tasks are trickiest
► Only one set of steps allowed
► No sections, stuff before and after steps must be in a specific order
| Data model

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
6. Middle-click to cancel the pending function
| Example…

► 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
4. Enter or select the new name
5. Left-click on OK to activate the name change
| Bad example…

► 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

► 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

► Tables
► Links
► Variables
► Conditions
► Having all the answers
| Stuff you probably don’t need to worry about

► Are they in a supported format?
► Where will they be stored?
► Do they rely on superimposed callouts?
| Other considerations – Graphics

► 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

► 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

► 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…

► 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

Questions
www.stilo.com/migrate
contact@stilo.com
THANK YOU!

Free conversion offer
Submit 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 Demo
Thursday, November 3, 2016
9:00 AM PST | 12:00 noon EST | 4:00 PM GMT
stilo.com/webinars

Helen St Denis: How to Prepare your Content for Conversion to DITA

Recomendados

Recomendados

Más contenido relacionado

Similar a Helen St Denis: How to Prepare your Content for Conversion to DITA

Similar a Helen St Denis: How to Prepare your Content for Conversion to DITA (20)

Más de Jack Molisani

Más de Jack Molisani (20)

Último

Último (20)

Helen St Denis: How to Prepare your Content for Conversion to DITA