1.
MIGRATING
DOCUMENTATION TO
XML AND DITA
Pat Farrell

2.
Pat Farrell: A Technical Information
Developer





Experienced in Many Different Areas
Information Developer
Leader, Manager
Programmer
Innovator

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

11.
PLANNING A CONVERSION TO XML AND DITA

12.
High Level End to End
Conversion

Overview

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


14.
A TALE OF TWO CONVERSIONS

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

16.
CONVERTING ASSORTED SOURCE FORMATS TO XML
AND DITA

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)