Presentation is loading. Please wait.

Presentation is loading. Please wait.

The Perfect Conversion: FrameMaker to DITA in 365 Days

Similar presentations

Presentation on theme: "The Perfect Conversion: FrameMaker to DITA in 365 Days"— Presentation transcript:

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

Download ppt "The Perfect Conversion: FrameMaker to DITA in 365 Days"

Similar presentations

Ads by Google