Pat Farrell, Migrating Legacy Documentation to XML and DITA


Published on

Pat Farrell is a TECHNICAL information developer who has developed a variety of custom solutions to increase productivity. This presentation is an overview of Pat's technical innovations followed by more detail of a conversion project he managed: migrating documentation to XML and DITA. Learn what you need to begin such a conversion project: workflow, considerations, and the benefits and fallbacks of using in-house or external resources for your XML or DITA conversion project.

Published in: Technology, Business
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Never Say No to Additional AssignmentsAlways meet deadlinesThe “Get it Done Guy”There isn’t a place I have worked in my life that wouldn’t want me back.
  • Many different innovations created in my spare time to help productivity
  • Think of this as brainstorming with bubble diagrams as taught in creative thinking problem solving coursesThe bubbles are the elements MacGyverism-made popular from the late 80s TV ShowAsks the questions:Where Am IWhere Do I Want to BeWhat Resources do I have to availableNavigate the Domain step by step to reach the goal
  • Many different innovations created in my spare time to help productivity
  • Many different innovations created in my spare time to help productivity
  • BMC had two business units start a conversion to XML, only one finished.
  • The conversion
  • Pat Farrell, Migrating Legacy Documentation to XML and DITA

    2. 2. Pat Farrell: A Technical Information Developer      Experienced in Many Different Areas Information Developer Leader, Manager Programmer Innovator
    3. 3. Information Development   Over 18 Years of Experience: Companies Positions  Datacert: Senior Technical Writer  DISYS: Contract Technical Communications Specialist at Schlumberger  BMC Software: Lead Information Developer  Candle Corporation: Technical Writer and Technical Support Representative  Heavy Construction Systems Specialists: Documentation Specialist
    4. 4. Information Development  Over 18 Years of Experience: Writing, Developing, and Leading  Duties • Develop online and hardcopy technical and marketing documentation for distributed, mainframe, and web-based software products • Develop help systems for distributed, mainframe, and web-based software products • Write and publish advisories to alert end users to issues between schedule product releases • Develop SDK documentation for external developer network • Lead documentation projects for several concurrent software projects • Support software products spanning development teams on varied release schedules • Develop documentation plans and schedules for information development teams on tight deadlines • Ensure compliance with corporate standards • Analyze documentation to create information models • Promote uniform structure across writing organizations • Use information models to single source common information • Work in agile and traditional product development environments • Collaborate with subject matter experts, executives, customers, and colleagues in global locations • Document custom software for high priority BMC Software client in Europe; the software was the early precursor to Business Service Management (BSM) • Work with usability engineers to integrate user assistance into Java-based software • Interview software developers to understand new technologies and provide appropriate information to end users
    5. 5. Information Development  Over 18 Years of Experience: Writing, Developing, and Leading  Duties, continued • Maintain internal and external customer-facing websites using Dreamweaver, SharePoint, and Clickability • Develop and maintain end-user help files for customer FTP download site • Bridge gap from registration site to FTP site • Provide user assistance for downloading product installation files • Develop internal documentation tools using AWK, C++, Visual Basic, Perl, FrameScript, and WinBatch to streamline production and improve end-user documentation • Develop FrameMaker plugin using AWK, Perl, and FrameScript to convert over 70,000 legacy mainframe messages with associated user information from FrameMaker 6.0 to XML (approximately 15,000 pages) • Manage common text insets in multiple FrameMaker books using Perl and FrameScript • Use XML to create conditional text Dreamweaver extension • Develop software and documentation development tools for external developer network • Provide level 1 and level 2 support of mainframe and distributed database monitors and tools to system engineers • Document customer issues in problem resolution database • Collaborate with software developers to identify and resolve software issues • Collaborate with information developers to ensure accuracy of technical documentation • Perform quality control testing of software products and documentation • Assist in network administration
    6. 6. Leadership  Manager, Leader, and Mentor  Various Leadership Positions Over the Years Senior and Lead Information Developer  • • • •  Develop documentation plans Coordinate release schedules with other groups Manage documentation deliverables and schedules for product group including the schedules and documentation plans of other writers Mentor new writers Retail Manager • • • • • • • • Hire, train, and supervise employees Develop employee training procedures Supervise employee benefits program Forecast annual revenue and budget annual expenditures Ensure OSHA compliance Develop sales campaigns Maintain daily cash reports; process accounts receivable and payable; manage sales tax Maintain all aspects of customer service
    7. 7. Development  Development Responsibilities at BMC Software Deliverable Description MUSE AT BMC we had two systems that would feed into the program temporary fix (PTF) process. Some groups used IBM Synergy, and some used a homegrown BMC system (SMUF/APTS). I was part of a team the created the MUSE, an Integration that would allow the Windows-based IBM Synergy system to create PTFs in the SMUF/APTS system. I wrote the interface in Perl that would request the new PTF numbers and update the database in SMUF/APTS. I was using libraries created by other developers on both sides that were called by the MUSE interface. Icon Create Tool When I was working on the BMC Developer Network, we a need to change our web-based icon creator tool into a desktop solution that developers could download. I used Perl and a Perl compiler to create a GUI for the tool and make it a standalone application with a Help system. Icon Compare Tool Our usability group was tasked with the effort to create a single icon repository. We had hundreds of products with hundreds of icons. Some images were identical with identical names, and some were different with identical names. I wrote a Perl script that would open each image and compare it pixel by pixel to every other image. The script would report on images that were the same with different names and images that had the same names but were different.
    8. 8. Innovation  Domain-Dependent or Closed-World Problem Solving  Where am I?  Where do I want to be?  What resources do I have to available?
    9. 9. Innovation  Delivering Innovative Solutions = Inspiring Confidence Innovation Description PDF Review Server Before Adobe had tools to distribute PDFs for group reviews, I developed a Webserverbased solution that allowed reviewers to see PDF comments from other reviewers while they reviewed a PDF and add their won comments that would be cumulatively collected in one PDF. Project Website Before we started using SharePoint we had a need for a project website. AT the time we hosted our own internal websites for different teams and projects. I created a site where doc team members could create project websites by filling out an online form. The websites were much a SharePoint sub site with user list, an issue tracking system, and document repositories. PDF Watermark I used the Adobe SDK and Visual C++ to create an Acrobat Plugin that would add Draft watermarks to review documentation. Before I created the tool adding and removing the watermark on draft documents was a tedious and time–consuming task. Help Posting Tool The PATROL group posted the online Help to the support Website periodically and the effort was hard to manage and coordinate. I developed a desktop application in Perl that would upload the Help systems to the staging server and update the index page of the help website. The tool would do some data validation and ensure consistency of the metadata. This solution allowed the help collection to stay up to date and saved countless person hours.
    10. 10. Innovations  Delivering Innovative Solutions = Inspiring Confidence Innovation Description Dreamweaver Conditional Text Extension For the development of the PATROL Central Web Console , we started using Dreamweaver as our development tool. We ere developing help for two similar consoles that shared about 80% of common content. Dreamweaver did not support any type of conditional text or processing, so I created a Dreamweaver extension in XML that allowed us to use Conditional text in Dreamweaver that was tagged by product code. The active product was turned on and of with a Dreamweaver menu command. FrameMaker Inset Manager Shortly before we moved toward XML and DITA, we had a need to single source a lot of our install and configuration information for the Mainframe products. I created a FrameMaker add on that provided the writers with a way to manage text insets at different levels of production in the books. This solution would manage the insets and perform preproduction tasks to the FrameMaker files at production time.
    12. 12. High Level End to End Conversion  Overview
    13. 13. What Do We Need to Do This Thing  Conversion Considerations What documents (content) are we converting?  Are we going to convert in house or use a third party?  Are we going to set up a central conversion group, distribute it to the writers, or some hybrid organization?  Do we have buy in from the content owners and writers?  When do we want to get this done?  Have we set everyone’s expectations correctly?  Do we have the required skills inventory? • Technical resource (innovation, tools, scripting, support) • Information architect / DITA resource • Trainer • Project management 
    15. 15. A Tale of Two Conversions at the Same Company  The Best of Times: Internal Conversion Best   No Third-Party Costs   Used Internal Resources   Content Owners Owned the Conversion  Dynamic, each subsequent conversion was a little easier and better as the conversion engine was adjusted    Other consistency changes were made during conversion, common phrases like contacting support Library items added during conversion          Worst  Used Internal Resources Best Used External Resources Was Faster Worst Expensive Uses Internal Content Owners Outside of the Conversion Required More time of Content Owners than Originally Thought Each iteration was a new charge Static, no adjustments mid stream Poor conversions did not import into the CMS without hours of rework Conversion Took a Little Longer   The Worst of Times: Third-Party Conversion The converted content never made it into production. Outcome  Outcome    Implemented and in production before the other business unit gave up on the project. Note: The business units shared the same CMS and production
    17. 17. The Point of Diminishing Returns  Setting Expectations: How Clean Can We Make the Conversion? “A poem is never finished, only abandoned.” Paul Valery, French critic & poet (1871 - 1945)