From Planning to Publishing: How Business Objects Migrated Documentation to DITA One Step at a Time

Loading...

Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

0 comments

Post a comment

    Post a comment
    Embed Video
    Edit your comment Cancel

    Favorites, Groups & Events

    From Planning to Publishing: How Business Objects Migrated Documentation to DITA One Step at a Time - Presentation Transcript

    1. FROM PLANNING TO PUBLISHING How Business Objects migrated to DITA COPYRIGHT © 2008, BUSINESS OBJECTS S.A.
    2. AGENDA
      • About us
      • Reasons for change
      • Migrating to DITA
      • Other Changes Required
      • How did we do?
      • Lessons Learned
    3. About Business Objects
      • Business Objects, an SAP company, is the world leader in business intelligence (BI) software
      • Headquarters in San Jose, CA and Paris, France
      • SAP is the world's leading provider of business software
      • Headquarters in Waldorf, Germany
      • SAP acquired Business Objects in 2007
    4. About Business Objects Documentation
      • Some quick numbers
        • 76 authors + 16 Production Staff
        • Nine sites
      • All content is written in English and localized to up to 10 other languages. Many documents are sim-shipped
      • Documentation teams have undergone rapid growth due to acquisition in the past 3 years
      • Began a move to XML based authoring in 2005
      • First complete release in mid 2007
    5. Reasons for Change
    6. Motivation for Change (1/2)
      • Fast growth due to acquisitions of other companies brought inconsistencies
        • Supported 6+ file formats
        • Different team structures and cultures
        • Different styles and guidelines
      • Authors suffered from inefficient processes
        • Manual processes made up a large portion of an authors work
        • Inconsistent tools and processes increased overhead
        • Writers spent time recreating existing content and manually copying/pasting instead of single sourcing
    7. Motivation for Change (2/2)
      • Translation process was expensive
        • Had to manage multiple character encodings
        • Large number of queries about English source content
        • Simultaneous shipment of software in 8 languages meant complex schedules and tight deadlines
      • Publishing process was overly complicated
        • Build times were as high as 2 days per deliverable per language
        • Multiple tools meant supporting multiple publishing processes
    8. Why did we choose XML?
      • Support for end-to-end Unicode encoding
      • Improved reporting on content and automated workflows
      • Separation of content and format: centralized, standardized output
      • But we needed a DTD…
    9. Why did we choose DITA?
      • DITA is a robust, industry-standard DTD
      • Topic based:
        • Provides better experience to our users
        • Makes reuse easier
        • Allows easier division of workload
        • Allows for rolling translation
      • Extensible architecture allows us to grow our information types with minimal effort
      • Allows us to impose constraints on topic and element structure, which encourages:
        • Minimalism: less extraneous information in standalone topics
        • Structural and stylistic consistency
    10. Migration Goals
      • Reduce production times
      • Support a single file format
      • Support a single publishing process
      • Minimize writing effort
      • Reuse content between deliverables and Business Units
      • End-to-end Unicode character encoding
      • Reduce the amount of required interaction between the localization, documentation and publishing teams
    11. Challenges and Restrictions
      • Existing knowledge of DITA was very low
      • Delivery of our largest doc set, in 9 languages, by 2007
      • In order to make the migration financially feasible, we had to migrate all of our content by the end of 2007
    12. Migrating to DITA
      • How did we get from there, to here?
    13. Components of a Successful Migration
      • Content and Reuse analysis
      • DITA specialization
      • New Authoring tools
      • Content Management System
      • Publishing process
      • Automated migration process
    14. Content and Reuse analysis
      • Conducted initial analysis, including:
        • Content analysis
        • Reuse analysis
        • Tools analysis
      • Designed a roadmap that included all teams
      • Decided to migrate to DITA 1.0 with no specialization
      • Reuse strategy would be implemented later in the project
      • Created rough plans for content alignment and rework
    15. Authoring Tool
      • Authoring tools may have to change
      • Any XML Friendly Editor should be fine
      • We selected XMetaL for DITA authoring
        • Highly visual XML Editor
        • Direct integration with our Content Management System
        • Several extension points
    16. Content Management System
      • A good Content Management Tool:
        • Is a common place to store files
        • Allows multiple people to work on the same files
        • Includes tools to find, group, sort and categorize information
        • Includes tools to publish information to other sources
      • A good Globalization Management Tool:
        • Supports the maintenance and deployment of multi-lingual versions of the same content
        • Custom formatting for each language
        • Provides additional tools for translation to the people that need them
      • We Selected Idiom’s WorldServer
    17. Publishing System
      • Nearly all publishing is handled through WorldServer
        • Exceptions for some release material or API material.
      • We single source to the following formats:
        • PDF x 3 styles (for review, product whitepaper, product guide)
        • CHM x 3 styles (for review, help, .NET2005)
        • HxS
        • Eclipse Help
        • HTML
        • Flat XML
      • All languages published using the same workflows
      • Initial customization of publishing process done in house
      • Hired an XSL Developer to work on publishing full time
    18. Automated Migration to DITA
    19. Creating an Automated Process
      • Most migration tasks can be automated
      • Some tools freely available
      • Any automation will require customization
      • Any customization will require technical expertise
      • No automation is perfect
    20. Process Overview
    21. Content Analysis
      • Authors conducted an analysis per deliverable
        • Identified content that would be obsolete for next major release
        • Analyzed content for appropriate structure and for potential reuse
        • Flagged difficult passages
    22. Pre-Processing
      • Make the input as simple, and uniform, as possible
        • Ensure adherence to current templates
        • Ensure adherence to corporate style guide
        • Remove ‘complicated’ constructions
        • Remove, or minimize, variables in text and call-outs in images
      • Move towards Topic Oriented style
        • Remove ‘book-isms’ where possible
        • Remove phrases such as ‘In this chapter’ or ‘on page…’
      • Structure content as much as possible
        • Consistent styles for blocks of text or inline elements improved the results of automation
    23. Scripted Migration
      • Migration to DITA was handled by our Publishing team
      • Scripts validated input files against the expected style sheets and templates
      • Framemaker Content
        • Frame files ‘published’ to DITA using a WebWorks template
      • Non-Framemaker Content
        • Files were published to a simplified HTML template
        • Content was converted to DITA using XSLT
      • Perl and XSLT were used to fine tune the output based on input from the author
    24. Three stages of DITA
      • Considered “Well Formed” if:
        • All tags that open are closed
        • All tags open and close in the same order
        • All attributes are quoted
      • Considered “Valid” if:
        • It is well formed
        • It conforms to the rules of the DITA DTD
      • Considered “Well Written” if:
        • It is well formed, and valid
        • Content conforms to our Style Guide
        • All tags are used correctly
        • Adheres to the correct Information Architecture (topic based, correct topic types are used when appropriate)
    25. Post-Processing
      • Content from migration was:
        • Guaranteed to be Valid
        • 80% Structurally correct
        • 20-80% topic based
      • Authors examined resulting files and improved content as necessary
      • No more than 10% of the content required re-writing
      • Most rewriting occurred because the input files were not topic based
    26. Final Steps
      • Content moved to new CMS
      • New published output compared against input files
        • Authors published content in familiar file formats, and compared the output against the original files
        • Authors published content to unfamiliar formats, and examined the output for oddities
      • Localization teams scoped the new files for loc impact
        • Translation Memories were adjusted programmatically where possible to reduce the impact of the changes
        • Input files changed programmatically to filter out some content from translation
    27. Other changes required
    28. Process Refinement
      • Continual improvement of migration process
        • Write scripts to migrate content to DITA
        • Write scripts to fine tune results
        • Test scripts on a sample set
        • Work with authors to identify pain points
        • Repeat…
      • Began enforcing stricter limitations on input files
    29. Changes for Authors
      • New Authoring Tool
      • New Content Management System
        • Direct integration with our authoring tool made managing files easier
        • New Content Management System easier to use, but less robust, than previous system
      • Software strings extracted from source code for use in error message guides
      • New Style Guide
      • Created new roles to handle concerns or confusion about the new format
    30. Changes for Localization
      • TM adjusted programmatically to reduce the impact of the new file format
      • Filters put in place to restrict the type of content that is exposed for translation
      • Workflows introduced to automate translation process
      • Interactions with vendors changed
      • New translation tools
      • New systems for translating graphics and screenshots (graphics now translated as text)
    31. Changes for Publishing
      • All content uses a single file format
      • Redesigned our publishing layer (several times) to be more extensible
      • Had to develop custom transforms for formats that were previously produced with proprietary software
      • Introduced tools for automated QA testing
      • Created processes to automate publishing of content, and incorporate output into the product build
    32. How did we do?
    33. Migration Goals: Revisited
      • Reduce production times
      • Support a single file format
      • Support a single publishing process
      • Minimize writing effort
      • Reuse content between deliverables and Business Units
      • End-to-end Unicode character encoding
      • Reduce the amount of required interaction between the localization, documentation and publishing teams
    34. Documentation in 2008 Criteria 2005 2008 Teams 6 14 Tools/Formats supported Word, Framemaker 6/7, Robohelp, (forehelp), JavaDoc, .Net XML XMetaL and DITA Content Management Perforce WorldServer Translation Trados WorldServer Publishing Combination of people, and WebWorks WorldServer Managing Published Content Fully manual 50% Automation (and more on the way!)
    35. Unexpected Benefits
      • Less source content
      • Increased adherence to standards and style guidelines
      • Collaboration across the sites
      • Improved flexibility with published output
      • The technology has given us more flexibility
        • Pulling content directly from source code
        • Direct integration with the build system
    36. Room for improvement
      • Lost some doc-related features
      • Process automation needs review
        • Some workflows not effective
        • Some workflows take too long, or are too tedious
      • Discovered commonalities in content that can be better represented through topic specialization
      • Information Architecture still fairly rudimentary
    37. Lessons Learned
      • Some additional wisdom we picked up along the way
    38. Education
      • General education should be provided early
        • Theoretical DITA
        • Topic Oriented Writing
        • Structured Writing Principles
      • Specific education should be provided as needed
        • DITA tag reference
        • Specific tools training
      • Classroom training can help improve confidence
      • Some material should always be available for on boarding
        • Skill with DITA is not yet common – some degree of training will need to be provided for any new hires
    39. DITA is not ‘Just XML’
      • DITA implies a content architecture and necessitates Information Typing
      • The DITA DTD is not simple
      • The Open Toolkit Transformations are not trivial
    40. Planning
      • Plan extra time for:
        • Migration workload for writers
        • Rewriting of content
        • Bug resolution before first release
      • Analyze the cost and the business case
        • Is it a worthwhile investment?
      • Get 100% commitment
        • Upper management commit to cost
        • Writers commit to change and to migration schedule
    41. Communication
      • Separate tools and content architecture decisions
        • Create a dedicated tools team
        • Leverage the tools as much as possible
      • Create a single point of contact for style changes
      • Determine tagging rules and ‘special cases’ as early as possible
        • With no guidance, authors are forced to make their own decisions
      • Not everything needs to be done at once, but clear milestones need to be set for when things will be done
    42. General
      • The migration requires some initial investment from all parties
      • The most difficult move for us was the move to Topic Oriented Authoring
      • The ‘cleaner’ your input, the better your output will be
      • Dedicate resources for customizing publishing output
    43. Questions?
      • Feel free to email me at dave.holmes@sap.com

    + Scott AbelScott Abel, 2 years ago

    custom

    2289 views, 0 favs, 1 embeds more stats

    Presented by Dave Holmes at Documentation and Train more

    More info about this document

    © All Rights Reserved

    Go to text version

    • Total Views 2289
      • 2222 on SlideShare
      • 67 from embeds
    • Comments 0
    • Favorites 0
    • Downloads 111
    Most viewed embeds
    • 67 views on http://www.doctrain.com

    more

    All embeds
    • 67 views on http://www.doctrain.com

    less

    Flagged as inappropriate Flag as inappropriate
    Flag as inappropriate

    Select your reason for flagging this presentation as inappropriate. If needed, use the feedback form to let us know more details.

    Cancel
    File a copyright complaint
    Having problems? Go to our helpdesk?

    Categories