The Perfect Conversion: FrameMaker to DITA in 365 Days

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

3
Your Presenters Today
Laura Bellamy, Information Architect

• Focus on information strategy and architecture
  for enterprise products
• DITA conversion project manager and expert

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

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 5000 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 (lttopicgroupgt)
• Conversion that didnt fill out critical
  publishing attributes
• Vendors 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
• lt?xml version"1.0" encoding"UTF-8"?gt
• lt!DOCTYPE concept PUBLIC "-//VMWARE//DTD DITA
  Concept//EN" "vmbase.dtd"gt

13
XML Requirements

• Well-formed and valid
• DTD should be clearly identified
• Public IDs are good
• lt!DOCTYPE concept PUBLIC "-//VMWARE//DTD DITA
  Concept//EN" "vmbase.dtd"gt
• SYSTEM IDs are bad
• lt!DOCTYPE concept SYSTEM ../dtd/vmbase.dtd"gt

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 ltuicontrolgt rather than ltbgt
• Avoid mapping to ltphgt
• If content is ambiguous or maps from one to many
  possibilities, conversion should map to an
  element then wrap the content with
  ltrequired-cleanupgt
• Example Monospace could map to ltcodephgt or
  ltfilepathgt

16
DITA Requirements

• Element Mapping Table

WarningNote style ltnote typewarninggt
Bold style with gt in between words File gt New ltmenucascadegt ltuicontrolgtFilelt/uicontrolgt ltuicontrolgtNewlt/uicontrolgt lt/menucascadegt
Optional string If inside a step ltstep importanceoptionalgt
Deprecated styles No tagging
17
DITA Requirements

• Element Mapping Table

Cross references starting with http// ltxref scopeexternal hrefhttp//www.vmware.com formathtmlgt
Internal cross references ltxref scopelocal hrefinstalling.xml typeconceptgt
Italics style ltrequired-cleanupgt
Monospaced style that can map to several DITA topics ltrequired-cleanupgt ltfilepathgtC/xyz/foobar.xmllt/filepathgt lt/required-cleanupgt
18
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 lttopicheadgt vs
  container topics
• Index terms
• Take advantage of conversion to adopt L10N best
  practices
• Move indexterms to ltprologgt
• Or move indexterms to the start of the block
  elements

19
DITA Requirements

• Conditions
• Map Frame conditions to product, platform, or
  audience
• Frame condition ESX_Embedded
• DITA condition productembedded
• Conrefs/Text Insets
• Spaghetti warning!
• Comments
• Frame conditions Comment
• DITA comment ltdraft-commentgt

20
Tool Specific Requirements

• Example1
• Maintain FrameMaker change bars
• Converted to XMetaL revision marks
• Example 2
• WebWorks Topic Alias markers
• DITA ltothermeta nameTopicAlias
  contentxyz/gt

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

24
Conversion Process - Graphics

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

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
• 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
• Dont think you have to do everything in-house
• Be honest with a positive attitude

38
Questions