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 Focus on information strategy and architecture for enterprise products DITA conversion project manager and expert Laura Bellamy, Information Architect

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. 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 Conversion Technical Requirements

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

17. DITA Requirements Element Mapping Table

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

19. 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: <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 toensure 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 • Don’t think you have to do everything in-house • Be honest with a positive attitude

38. Questions