1. The Perfect Conversion: FrameMaker to DITA in 365 Days
Yas Etessam
XML Architect, Technical Communications, VMware
Laura Bellamy
Information Architect, Technical Communications, VMware
April 2009

2. Yas Etessam, XML Architect
Your Presenters Today
Yas Etessam, XML Architect
Designs and delivers standards based, globalization ready content development environments
XML/SGML expert
Contributor to the OASIS DITA standard
Teresa 2

3. Laura Bellamy, Information Architect
Your Presenters Today
Laura Bellamy, Information Architect
Focus on information strategy and architecture for enterprise products
DITA conversion project manager and expert
Teresa 3

4. About VMware & Virtualization
Global leader in virtualization solutions
Public company with more than 5,500 employees worldwide
Virtualization:
Separate software from hardware
Run multiple operating systems & applications simultaneously on a single computer
Drag and drop to move applications from one machine to another
Founded in 1998
Acquired by EMC
Spun out for IPO in August 2007
$1.83 Billion in revenue, 88% growth since last year

5. 2008 Product Line • VMware VirtualCenter • VMware Converter
• VMware Capacity Planner
• VMware Site Recovery Manager
• VMware Virtual Desktop Infrastructure
• VMware ACE
• VMware Lab Manager
• VMware DRS with DPM
• VMware High Availability
• VMware Consolidated Backup
• VMware Storage VMotion
• VMware VMotion
• VMware Update Manager
• VMware ESX Server
• VMware ESX Server 3i
• VMware Virtual SMP
• VMware VMFS
• VMware Server
• VMware Workstation
• VMware Fusion
• VMware Player

6. Our 365-Day Story Success story
Conversion of an enterprise product library
From unstructured FrameMaker to DITA topics
Conversion during an active release cycle
Single sourcing help and manuals
Writing and production team had no DITA experience

7. Conversion Challenges
Legacy content in FrameMaker converted to VMware DITA 1.1 XML
Converting content takes planning, team work, and a commitment of resources
Vendor selection
Quality conversion is key
Turnaround time
Do multiple test runs of the same content with different vendors
The move to a new authoring methodology requires a cultural shiftl
Trained 45 writers

8. Conversion Technical Requirements
Prerequisites
Understand the target DITA data model
Ensure that the publishing tools are ready to support the converted content
Conversion: In-house conversion versus outsourcing
In-house requires technical knowledge, extensive resources, tools support, and QA
Leading aerospace producer had their staff convert content with Mif2Go, staffing hours cost over 60K
Test drive conversion tools
Send over content and see what you get back
Not all conversions are equal

9. Vendor #1 No hierarchy in the DITA map All topics in the same folder
Conversion that would only work for Help outputs but not for PDF outputs (<topicgroup>)
Conversion that didn’t fill out critical publishing attributes
Vendor’s lack of experience and DITA referencable customers

10. Vendor #2 DITA map hierarchy
Willing to work with our folder and filenaming requirements
Recognize publishing and conversion are linked
Cost effective
We helped educate them on DITA

11. DITA Requirements Stack
Tool Specific – Frame, XMetaL, WebWorks
Conditions
DITA Element Mapping and Specializations
DITA – Maps and Topics
XML
Unicode encoding

12. Encoding Requirements
Laying groundwork for localization
Unicode
UTF-8 is the best target encoding
Byte Order Marks
XML encoding declaration
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//VMWARE//DTD DITA Concept//EN" "vmbase.dtd">

13. XML Requirements Well-formed and valid
DTD should be clearly identified
Public IDs are good:
<!DOCTYPE concept PUBLIC "-//VMWARE//DTD DITA Concept//EN" "vmbase.dtd">
SYSTEM IDs are bad:
<!DOCTYPE concept SYSTEM “../dtd/vmbase.dtd">

14. DITA Requirements Which version of DITA will you be using?
Specializations?
Bookmap?
DITA maps with .ditamap extension
DITA topics with the .xml extension
One topic per file
DITA map hierarchy
Correct information types: concept, task, reference, and glossary
Discuss folder structure

15. DITA Requirements Element Mapping
Consistent use of Frame or Word templates is key
Every FrameMaker style will be mapped to either:
A target DITA element
Nothing (deprecating the style)
Map to the best semantic element
Map to <uicontrol> rather than <b>
Avoid mapping to <ph>
If content is ambiguous or maps from one to many possibilities, conversion should map to an element then wrap the content with <required-cleanup>
Example: Monospace could map to <codeph> or <filepath>

16. DITA Requirements Element Mapping Table WarningNote style
<note type=“warning”>
Bold style with > in between words
File > New
<menucascade>
<uicontrol>File</uicontrol>
<uicontrol>New</uicontrol>
</menucascade>
“Optional:” string
If inside a step:
<step importance=“optional”>
Deprecated styles
No tagging 16

17. DITA Requirements Element Mapping Table
Cross references starting with
<xref scope=“external” href=“ format=“html”>
Internal cross references
<xref scope=“local” href=“installing.xml” type=“concept”>
Italics style
<required-cleanup>
Monospaced style that can map to several DITA topics
<required-cleanup> <filepath>C:/xyz/foobar.xml</filepath>
</required-cleanup> 17

18. DITA Requirements DITA Maps Index terms
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: <topichead> vs container topics
Index terms
Take advantage of conversion to adopt L10N best practices
Move indexterms to <prolog>
Or move indexterms to the start of the block elements 18

19. DITA Requirements Conditions Conrefs/Text Insets Comments
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: <draft-comment>

20. Tool Specific Requirements
Example1:
Maintain FrameMaker change bars
Converted to XMetaL revision marks
Example 2:
WebWorks Topic Alias markers
DITA: <othermeta name=“TopicAlias” content=“xyz”/>

21. 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

22. 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

23. 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 23

24. Conversion Process - Graphics
Graphics team converts graphics to SVG format
Writers will need to produce new alt text for each graphic 24

25. 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
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

26. 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

27. 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?

28. 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

29. 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)

30. 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

31. 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.

32. Project Management
Staffing
Scoping
Budgeting
Managing

33. 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

34. 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

35. 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?

36. Manage the project Transparency is key Keep records Gather metrics
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

37. 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

38. Questions