Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

The Trip to DITA


Published on

Sometimes, a spontaneous road trip can be a lot of fun, as long as you’re willing to take the good with the bad—getting lost, car trouble, unfriendly (or just plain weird) natives, bad diner food. Usually, though, the most successful trips involve planning, roadmaps, and best of all, guidance from people who’ve already been there.

The journey from traditional, deliverable-centric content creation to DITA-based content creation falls into this second category. In this session, we talk about one small publication group’s experience moving to DITA, from the initial discussions to the successful implementation of a FrameMaker-based, end-to-end publication process. Here are some of the high points of the project; we’ll discuss our decision-making process and some of our technical approaches in detail in the session.

Published in: Technology

The Trip to DITA

  1. 1. About the Trip to DITAThe transition from traditional, document-centered content creation to DITA-based content creation requires substantial planning for the journey to besuccessful.The journey of one small documentation team took from unstructured Frame toStructured FrameMaker using the DITA content model. This will includeinitial discussions, strategic development and steps required for a successfulimplementation of a FrameMaker-based, end-to-end publication process.
  2. 2. About this Presentation An overview of the migration from unstructured to structured authoring A specific process for preparing FrameMaker documents for conversion to DITA. Challenges faced during the year-long journey from unstructured to structured authoring. A model other documentation teams can use to re-organize existing documents and to create new documents going forward to help ensure their FrameMaker content is well-positioned for a successful, efficient conversion effort.
  3. 3. Interviews and Report Interviews with team members and group discussions Focus on business drivers, team readiness, content analysis, tools and disparate processes. Offered an opportunity to discover team members’ preparedness. Report outlined summary of findings with requirements and action plan for a phased implementation. Recommendations, detailed development steps and basis of agreement.
  4. 4. Goals Optimize authoring, translation and publishing cycle to help meet increased need for translations Reuse content from one publication to another quickly and consistently Decrease time to develop and update manuals Automate labor-intensive tasks giving writers more time for research and improving content Prepare for a future Content Management System (CMS) implementation
  5. 5. BudgetClient workgroup gathered information for a yearprior to contacting consultant. Spread expenses overtwo years and four phases. Phase 1: Assessment of business goals, requirements analysis, content audit, content analysis, process mapping and process re- engineering Phase 2: DITA training, content modeling, prototype project, assess content management technologies Phase 3: Write a CMS RFP based on business requirements, distribute RFP to potentials vendors, proof of concept with qualified vendor(s) Phase 4: Buy and implement CMS
  6. 6. Content Audit Writers selected three publications representative of their work products Consultants worked with client team to performed content audit  Determine how well content could be broken into topics  Determine what rewrite required  Develop method for determining reuse  Spreadsheet for tracking  Selected book with most reuse (the beta book, 80%) and used that for development
  7. 7. Content Modeling DITA was selected as the content model Content modeling focused on chunking topic by types and identifying attributes audience, product, language, software version and compliance requirements Used content audit spreadsheet as a guide Content modeling was a client training exercise
  8. 8. Tool Selection Hard copy and PDF formats only Primary requirement is PDF for print Writers had no experience with structured authoring Writers already experienced Frame users  Migrated from unstructured (7.1) to structured 9 Completely Frame based publishing process preferable to an XSL-FO publishing process Using default DITA functionality, not DITA-FMx  Yeah, we know FMx is better!
  9. 9. Reuse Based on content audit:  Text: 85%  Graphics: 70% Three products, four document types Import XML software file as conrefs for variables Conditions
  10. 10. Clean Template Standardize style names, eliminate un-used styles Clean and standardize all templates before conversion Client made good decisions to simplify template for translation:  No hyphenation No text in cross-references
  11. 11. Conditions Eliminated conditional text and replaced with @product, @audience (pick list built in EDD) Structure changes needed to accommodate Decisions made about level of granularity for these attributes  topic-level  element-level  sentence level?  phrase level? More tracking required with last two levels
  12. 12. EDD Based on “default” DITA EDD that ships with FrameMaker Unnecessary rules removed or simplified Client uses only ~40% of tagset but unused elements not deleted from EDD Use of @outputclass on several elements to specify formatting not predictable via context  Full-page images vs in-column images  Ad hoc table cell alignment No specialization or DITA plug-ins
  13. 13. Conversion Table Template standardization Template style usage very consistent—YAY! “Crosswalk” spreadsheet developed to map existing template styles to equivalent DITA elements
  14. 14. Document Conversion Conversion table “wrapped” every instance of a format in the appropriate element Higher-level wrapping largely manual—writer discretion needed to determine appropriate topic type, etc. Converted each chapter document into one large XML doc Consultants/writers then determined how to “split” large doc into individual topics  Naming convention  Not a mass conversion Consistent level of granularity
  15. 15. Variables Original template contained 100+ variables corresponding to menu options in software Value of variables came from developer-generated XML file Easily translatable; kept this functionality Created separate file containing each variable as a conref source (<varname>)  This file still developer-generated, though now in DITA Still easily translatable
  16. 16. Images Most images in original documents were line drawings of screen overlaid with text boxes containing variables, simulating screen shots Easily translatable, reduced need for language- specific images Initial goals was to use SVGs (Scalable Vector Graphics) to maintain this functionality (i.e. translatable text as element within SVG) FrameMaker cannot “look inside” SVG code; this solution not workable at present For same reason, cannot show/hide callouts (Frame cannot interpret the @display value) Use SVGs to lay groundwork for CMS
  17. 17. Images Image sizing  Frame uses DPI, converts to @height, @width  No units in XML code  @height, @width not accessible in Frame Image paths  Frame uses backslashes by default  Cannot enter backslashes manually, must change to forward slashes Re-linking image via Missing File dialog does not dynamically update @href path
  18. 18. Translation Prefix for <note> elements, some <title> elements and other items language-specific Decision made to generate these items using EDD rules based on @xml:lang  One template per document type vs. separate template for each language  Non-English PDFs produced by the translation agency, so this simplification was essential Numbering/bulleting not language-specific but groundwork laid if changes in future
  19. 19. Tables Table handling  Mapping between DITA table elements/ attributes handled by read/write rules  Trick is learning what corresponds to what in Table Designer and Custom Ruling & Shading dialogs  Most formatting applied based on <tgroup> not <table> <colspec>, <spanspec> in XML code but not in Frame—can be confusing
  20. 20. Revisit Template Client focused on page layout Ad hoc tables modifications required narrowing Impact on EDD Revisions along the way; discovery of “exceptions” Writers rethinking items in light of increasing DITA knowledge
  21. 21. Beta Project Representative of typical book but not a production project Used to test every aspect of development from topic types, templates, EDD, conversion, reuse, book building and training. Smaller sample of beta book for translation testing Project book is leveraged for production
  22. 22. AXCM Free Frame plug-in from West Street Consulting  Filters files for @product, @audience using XPath filters  Colors documents to emulate conditional text  Filters topics on the fly More robust than Frame’s built-in Filter By Attribute For this publishing process, preferable to applying a ditaval file
  23. 23. Basic Publishing Process Ditamap for each book chapter Save ditamap as composite Frame file  Set numbering, other doc properties  Not using “Prompt for Ditaval” option  Not using bookmap Add composite Frame files to Frame book Filter files for @product, @audience using AXCM Generate/update TOC, Index Publish book as PDF
  24. 24. Installation Upgrade to FrameMaker 9 Set up structured application Install AXCM
  25. 25. Demonstration Three days on-site to rollout template Goals:  Instruct writers in DITA authoring  Get writers familiar with tagset  Get writers familiar with Frame’s DITA implementation and interface Explain conversion process Additional day on-site to instruct writers in basics of EDD creation and maintenance  Writers not ready to take over EDD but they understand what’s “under the hood”
  26. 26. Workflow Requirements CMS is just one part of a unified content strategy Specification detailing client use case Requirements focus  Support for DITA, content reuse, user interface, support encoding for languages, translation streaming and branching capacities, automated, multi-channel publishing  Cost  Criteria for migration Use to produce a Request for Proposal (RFP) include information about existing implementations, licensing, configuration, core technologies, maintenance, support, customization, training and cost
  27. 27. Request for Proposal RFP is offered to major CMS vendors and vendors are given the opportunity to respond. Evaluate responses Based on requirements, select vendors who respond to the RFP with a proof-of-concept
  28. 28. Proof of Concept Beta book used for Proof of Concept Vendors use client content to demonstrate how their system meets client needs Compare Proof of Concept results with CMS Requirements Evaluate vendor relationship, expertise
  29. 29. Contact Information Mollye Barrett ClearPath, LLC Leigh White ElementalSource, LLC