The Perfect Conversion: FrameMaker to DITA in 365 Days

DITA Requirements Element Mapping Table

WarningNote style Bold style with > in between words

File > New

“Optional:” string Deprecated styles

File New

If inside a step:

No tagging

DITA Requirements Element Mapping Table

Cross references starting with http:// Internal cross references

Italics style Monospaced style that can map to several DITA topics

C:/xyz/foobar.xml

DITA Requirements

DITA Maps

Topic reference hierarchy must be maintained Large deliverables with multiple authors should have submaps Nice to have: navtitle with the topic title pulled in Map to the correct elements: vs container topics

Index terms

Take advantage of conversion to adopt L10N best practices Move indexterms to Or move indexterms to the start of the block elements

DITA Requirements

Conditions

Map Frame conditions to product, platform, or audience Frame condition:

ESX_Embedded

DITA condition:

product=“embedded” Conrefs/Text Insets

Spaghetti warning!

Comments

Frame conditions:

Comment

DITA comment:

Tool Specific Requirements

Example1: Maintain FrameMaker change bars Converted to XMetaL revision marks Example 2: WebWorks Topic Alias markers DITA:

Technical Gotchas

Publishing

Not enough to be valid XML, need to be able to publish with the DITA Open Toolkit and avoid errors and warnings where possible

Cross reference clean up

No automated way to create reltables Manual task

Whitespace

Delete empty paragraphs and extra spaces

Automatic naming

File naming and folder naming Windows limits on path/folder names

Conversion Process – Content Workshops

Writers and editors hold DITA Content Workshops to prepare for the conversion process Schedule the meeting for 1 month before the scheduled conversion Review a sample of a deliverable in a 1-2 hour meeting.

Look for items that are not supported in your element mapping table Identify content that is not organized by topic type Identify content that does not stand alone Use this meeting to discuss the conversion process with the writer

Conversion Process - Preconversion Cleanup

Writers implement preconversion cleanup of the FM documents to ensure DITA-ready structure and consistency Follow the FrameMaker template rules Minimize content Organize content by topic type Write meaningful headings and titles Review and standardize conditional text Structure tasks for DITA Reduce internal cross references and citations Remove external cross references Remove screenshots

Conversion Process - Graphics

Graphics team converts graphics to SVG format Writers will need to produce new alt text for each graphic

Conversion Process – Submit for conversion

Deliver FrameMaker Source

Schedule conversion shipments with the vendor Production sends the FrameMaker files to the conversion vendor. Max 10 day turnaround of content

Information Typing

Conversion vendor sends back a spreadsheet Writer verifies the topic types, chunking, and file names in the spreadsheet 1.

2.

3.

4.

5.

Postconversion Cleanup and QA

Production receives the XML and starts postconversion cleanup and QA Production publishes the XML to PDF and WebWorks Production adds any special metadata and sets up the link relationships for help Production stores the content in a repository and informs the writer Writers complete postconversion items and take final steps to create solid DITA content

Conversion Process Gotchas

Do not introduce new FM styles or conventions

No new styles No special headings, such as “Prerequisite”

Verify FM files before conversion

Check the nesting levels of topics Remove any styles not supported in your element mapping table

Document potential reuse and related linking

Unique opportunity to evaluate every topic

Spell check before conversion

Your XML editor might not have map-based spell check

Prepare writers to be without content

Information Architecture Strategy

Know your information

Gather an accurate picture of what information you currently have to understand element mapping requirements, expected topic types, template requirements, and potential reuse

Define the conversion goals

What is the primary driver for the conversion: save translation cost, improve user experience, increase reuse?

Do you need quick & dirty or can you focus on quality?

Define documentation standards

Information should match future corporate direction and goals Do you need to meet/exceed industry standards?

Postconversion DITA goals

Increase content reuse

Implement the reuse identified in FM files Do a reuse analysis during postconversion Start reusing entire topics and conrefing pieces of information

Task modeling

Leave the sequential book model behind Reorganize converted content into a proper task flow Implement collection-types

Work toward consistency

Training and documentation

End-user training

Create a training plan Who will create the materials? Give the training?

Guidelines

The DITA language ref might need to be modified to present only the tags that you support DITA introduces new features. Decide how you want to use these features and educate your team

Process documentation

Writers need instruction for how to build output, implement company style and guidelines

Templates

Include descriptive text in new templates and boilerplate content (Preface, Appendix, Glossary)

Tools development and support

Building new tools

Let the content needs drive the tools development

Supporting the team

Allocate resource to supporting new DITA users Create a support team and define a communication strategy where you can quickly respond to questions Decide how to rollout tools updates and provide continuing education

Evaluate the end result

Code reviews

Ensure tagging quality and consistency by reviewing the DITA files Give writers 1 month to learn and work with content Communicate tagging errors and look for patterns

Check the output

Might need to adapt style sheets in response to new DITA features

Gather feedback

Ask end users about the new experience: technical reviewers, beta customers, trainers, etc.

Project Management

Staffing Scoping Budgeting Managing

Staff the project

Hire experts

It is too difficult to learn DITA when you start a conversion project Identify the skills that your team is missing What can you train for and what do you need to outsource

Expect staff roles to change

What new responsibilities will existing staff take on?

How can you use existing staff in new ways?

Understand the time demands on existing staff who are new to DITA

Scope the project

Create a pilot team

Define the pilot requirements Localization Size and complexity Release schedule Personal attitude and working style Document expectations and goals Limit yourself at first Easy to add more later Evaluate the pilot result and improve the process Create a rollout plan

Budget the project

Get cost estimates from vendors

What are the hardware/software requirements How much time will development, testing, and bug fixes take Will conversion costs be based on page count, number of batches sent for conversion, or a combination of above?

Budget time with vendor

Before signing a contract define turnaround times with the vendor How much time will the content be unavailable Consider time zone differences, take advantage of them to reduce time content is unavailable

Budget time in-house

How much total time will content be out of hands of writers What are the resource costs for your team? Do you need to hire?

Manage the project

Transparency is key

Communicate failures and successes Clearly state risks and limitations Manage expectations List priorities

Keep records

Create a repository for project content Record all decisions

Gather metrics

Others can benefit from the pilot phase

Reward success

Summary

Even with automation and vendors, conversion effort is proportional to the amount of content and its complexity Conditions Multiple products Overlapping release cycles Extensive reuse Localized to eight language Each conversion project is new to that writer You and the writers are on the same team Don’t think you have to do everything in-house Be honest with a positive attitude

Questions