• Save
The Trip to DITA
Upcoming SlideShare
Loading in...5

The Trip to DITA



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

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.



Total Views
Views on SlideShare
Embed Views



2 Embeds 22

http://www.linkedin.com 17
https://www.linkedin.com 5



Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

    The Trip to DITA The Trip to DITA Presentation Transcript

    • 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.
    • 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.
    • 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.
    • 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
    • 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
    • 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
    • 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
    • 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!
    • Reuse Based on content audit:  Text: 85%  Graphics: 70% Three products, four document types Import XML software file as conrefs for variables Conditions
    • 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
    • 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
    • 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
    • Conversion Table Template standardization Template style usage very consistent—YAY! “Crosswalk” spreadsheet developed to map existing template styles to equivalent DITA elements
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • AXCM Free Frame plug-in from West Street Consulting  www.weststreetconsulting.com 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
    • 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
    • Installation Upgrade to FrameMaker 9 Set up structured application Install AXCM
    • 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”
    • 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
    • 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
    • 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
    • Contact Information Mollye Barrett ClearPath, LLC www.clearpath.cc mollye@clearpath.cc www.linkedin.com/in/mollyebarrett Leigh White ElementalSource, LLC http://elementalsource.pbworks.com/ elementalsource@gmail.com www.linkedin.com/in/leighwwhite