From FrameMaker to FrameMaker, Growing a DITA-Capable Department


Published on

Presented at CMS/DITA NA 2009

Smaller organizations are starting to feel the need for DITA. For small organizations with limited staff resources and smaller budgets, it's harder to plan and execute the move to DITA from traditional publishing applications and processes. As DITA's adoption continues to spread to smaller organizations, people continue to ask very basic questions. In this presentation, we explain why Software AG chose to convert legacy FrameMaker documentation to DITA, while continuing to use FrameMaker as their post-conversion DITA editor. We describe the issues we faced in making this decision, our activities in preparation for conversion, and the post-conversion activities needed to provide DITA content equivalent to the original legacy documents. Throughout, our emphasis has been to bring all staff along with us as we make our move to a structured-authoring environment.

Published in: Technology
1 Comment
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

From FrameMaker to FrameMaker, Growing a DITA-Capable Department

  1. 1. From FrameMaker to FrameMaker Growing a DITA-Capable Department Larry Owen – Software AG USA, Inc. Elizabeth Fraley – Single-Sourcing Solutions, Inc.
  2. 2. Single-Sourcing Solutions Our approach is to provide just the right amount of assistance to take customers from planning to production. Who we are Our team will help you jump start 2 Single-Sourcing Solutions was founded in 2005 your program by: © 2008 PTC The Arbortext-dedicated distributor of PTC’s complete Dynamic Publishing Assessing your specific needs for the solution in the West: near term and long term ! Arbortext Content Manager Developing customized stylesheets ! Arbortext Architect ! Arbortext Editor Collaboratively working with you to create the optimum learning path for ! Arbortext Styler your team ! Arbortext IsoDraw and IsoDraw CAD Process Acting as a mentoring resource as your ! Arbortext Publishing Engine internal team gains momentum ! as well as other Arbortext associated products. Converting legacy data to support your Our customers cover a vast range of verticals from Aerospace & Defense, changing publishing needs Automotive and Industrial, Technology, Services & Government, Publishing, and Life Sciences. Our team has over 25 years in Technical Documentation publishing, editing, and conversion experience. Over a 8 years experience with the Arbortext toolset. We will convert 100 pages at 50% discount so you can evaluate us Over 10 years experience in the practical development and deployment of mission-critical, custom XML development.
  3. 3. Software AG ¬ The world‘s largest independent provider of business infrastructure software ¬ One of the 25 largest enterprise software vendors ¬ 3600 employees operating in 50 countries ¬ Global Headquarters – Darmstadt, Germany ¬ U.S. Headquarters – Reston, Virginia ¬ Celebrating our 40th anniversary year From FrameMaker to FrameMaker | 4/28/09 | Page 3
  4. 4. Software AG Documentation Group ¬ Staff of 30 writers and managers ¬ Offices in four countries ¬ Darmstadt, Germany ¬ Sofia, Bulgaria ¬ India ¬ Bangalore ¬ Chennai ¬ United States ¬ Reston, Virginia ¬ Denver, Colorado ¬ Alviso, California ¬ Bellevue, Washington ¬ Plus some lucky telecommuters ¬ Two widely divergent methodologies From FrameMaker to FrameMaker | 4/28/09 | Page 4
  5. 5. Can this Marriage be Saved? The U.S. Doc Team The Darmstadt Doc Team ¬ Legacy FrameMaker ¬ XMetaL and XML (SAGDOC) ¬ Distributed output generation ¬ Automated server-based output ¬ Primary output is PDF ¬ Primary output is HTML ¬ VCS is Perforce ¬ VCS is CVS Yes, absolutely! ¬ Doc integration working group ¬ DITA will be our common ground ¬ Open standard with wide acceptance ¬ Common language, whichever editor we use ¬ Common VCS (okay, we would have done that anyway) ¬ Ability to share content with other groups From FrameMaker to FrameMaker | 4/28/09 | Page 5
  6. 6. Why choose FrameMaker? ¬ We can continue to output high-quality PDF ¬ Our current users expect full-featured PDF documentation ¬ Complete guides, not single-concept documents ¬ Hypertext-linked TOC, index, and cross-references ¬ Even when the primary content is online help.... ¬ Through DITA, we can offer more HTML content to new users ¬ One editor is enough, thank you ¬ FrameMaker is an XML editor? ¬ Writers can focus on learning structured documentation ¬ Writers will still have to juggle DITA and legacy content From FrameMaker to FrameMaker | 4/28/09 | Page 6
  7. 7. The FrameMaker XML Penalty - 2005 ¬ Geek alert! ¬ Knowledge of FrameMaker templates ¬ Knowledge of the Document Type Definition (DTD) ¬ Element Definition Document (EDD) ¬ XML read/write capability ¬ Read/write rules ¬ FrameMaker Developer Kit (FDK) ¬ Extensible Stylesheet Transformations (XSLT) ¬ No official FrameMaker support for DITA From FrameMaker to FrameMaker | 4/28/09 | Page 7
  8. 8. The FrameMaker and DITA Today ¬ FrameMaker 8 (and later) supports DITA ¬ Knowledge of FrameMaker templates ¬ Knowledge of the DITA DTD ¬ Knowledge of EDDs ¬ XML read/write capability ¬ DITA-FMx ¬ FrameMaker plug-in ¬ Joint offering by Leximation and Silicon Software ¬ Enhanced usability ¬ The lightning proof of concept From FrameMaker to FrameMaker | 4/28/09 | Page 8
  9. 9. The DITA Development Project ¬ The decision to go forward – August 2008 ¬ The commitment: ¬ Build out the DITA structure application ¬ Develop roll-out strategy and plan ¬ Develop and deliver initial training (FrameMaker-DITA 101) ¬ Get initial projects under way by December 2008 ¬ Key roles: ¬ Management ¬ Project management ¬ Technical development ¬ Information architect (we are not there yet) From FrameMaker to FrameMaker | 4/28/09 | Page 9
  10. 10. Some Basic Assumptions ¬ A chapter-based orientation ¬ Level 1 of the DITA Maturity Model ¬ Fits well in our PDF-centric world ¬ Easier acceptance by writers ¬ Currently, there is little reuse of content ¬ Selective migration of documents ¬ Based on translation priorities ¬ Generally, user’s guides first ¬ Some documents or products may never be migrated ¬ No specializations, no way, no how! From FrameMaker to FrameMaker | 4/28/09 | Page 10
  11. 11. Getting Ready for DITA ¬ FrameMaker template simplification ¬ Removal of admonition tables ¬ Clean-up of tables in general ¬ Culling of paragraph and character styles However, the basic template looks mostly the same. ¬ Rethinking Graphics ¬ Composite graphics and XML do not mix ¬ Call-outs need to be translation friendly Solutions? If you know a good one, please share it with us. From FrameMaker to FrameMaker | 4/28/09 | Page 11
  12. 12. Migrating Legacy Content ¬ Do it ourselves? ¬ Brute force ¬ The FrameMaker conversion table ¬ Our solution is – Single-Sourcing Solutions ¬ For us, this is the cost-effective way to go ¬ Prior relationship in conversion to DocBook From FrameMaker to FrameMaker | 4/28/09 | Page 12
  13. 13. Conversion: Preparation Create maps for the simple things Character formats Paragraph formats © 2008 PTC – “Topics” to proper DITA topics Maps for the simple things Graphics Restructuring content Dividing up information Cross references Text Inserts Conditional Text Equation handling
  14. 14. Conversion: Prework Identify chunks and information content in the source Topic boundaries File names © 2008 PTC Topic types Communicate these decisions Automatically Let the source be the guide Before converting, we deliver preconversion reports to validate Topics, types, count Character and paragraph styles used in document under conversion Filenames, collisions ID conflicts
  15. 15. Conversion: Source to DITA Turnaround time Our minimum turnaround time is 3 business days – Shortest is 1 day! We support many different output options © 2008 PTC Multiple chapters One file with nested topics Topic files split automatically or by file markup Output is always Standard DITA, usable in any authoring product that supports it Our conversion improves as sample size grows Decrease conversion errors Eliminate undesirable output Uncover unexpected template usage Customers can change their minds! What comes in goes out!
  16. 16. Post-Conversion Actions ¬ Exactly what you might expect: ¬ Make sure elements are used properly ¬ Redo cross-references ¬ Insert graphics (the new versions, of course) ¬ Pretty up the tables ¬ Resolve contents of required-cleanup element ¬ Make note of items to be tweaked for the next batch of files to be converted. From FrameMaker to FrameMaker | 4/28/09 | Page 16
  17. 17. But Wait, There’s More! ¬ Establish and document guidelines ¬ Staff the hotline ¬ Provide templates and snippets to make content development easier ¬ Provide supplemental how-to information (FrameMaker-DITA 102) From FrameMaker to FrameMaker | 4/28/09 | Page 17
  18. 18. How Are We Doing? ¬ New content development in previously migrated documents ¬ New content development in a completely new module ¬ First DITA content will be delivered in June 2009 From FrameMaker to FrameMaker | 4/28/09 | Page 18
  19. 19. What’s Next for Us? ¬ Continue to execute against our migration plan ¬ Get some experience with topic-oriented content ¬ Evaluate the DITA OTK (HTML, Eclipse help) ¬ Evaluate FrameMaker 9 ¬ Develop expertise in XSLT (and maybe the FDK) From FrameMaker to FrameMaker | 4/28/09 | Page 19
  20. 20. Questions? ??? From FrameMaker to FrameMaker | 4/28/09 | Page 20
  21. 21. Thank You!