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. DenisConversion 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 nowWhat 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



Questionswww.stilo.com/migrate

[email protected]

THANK YOU!



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

helen st denis: how to prepare your content for conversion to dita

Leadership & Management