Introduction

In the following article, Deb Lockwood of CSG Systems, a Colorado-based customer interaction management firm, details how she and her team succeeded in completing the conversion of over 11,000 pages of documentation. Her article is an excellent illustration of just how critical it is to convert your documentation to the right format, and it also serves as a reminder of how much work and management effort goes into a do-it-yourself conversion.

Converting in-house is the right answer for some, but it is neither cheap nor easy. Lockwood and her team succeeded in their in-house conversion effort because they took it seriously and did it right. Their conversion project was completed over the course of six months, and took an estimated 4,106 working hours (around 2.8 pages per person-hour).

In a recent conversation I had with Ms. Lockwood, she answered a few questions about her experience. She said that the decision to attempt the conversion in-house was, in fact, based on her department’s Lead System Developer’s extensive experience with FrameMaker conversions.

Now, almost eight years after the conversion to FrameMaker, were the benefits of the conversion worth the effort?

“Definitely. We are still using FrameMaker for our documentation, which has allowed us to get into the world of Agile Software Development and the single-sourcing of content.”

Any advice to other companies considering an in-house conversion?

“Yes. Plan!”

It's sound advice.

— Emily Burns, DCLnews

THE SITUATION

CSG Systems, Inc. is a leading provider of outsourced billing, customer care, and print and mail solutions and services for the convergent broadband and Direct Broadcast Satellite (DBS) markets. Clients include Adelphia, AOL Time Warner, Brighthouse, Comcast, and Echostar.

"CSG’s technical documentation department produces user guides and release communications to support CSG’s software applications."

CSG’s technical documentation department produces user guides and release communications to support CSG’s software applications, and these materials are written for several different levels of readers (e.g., software developers, customer service representatives).

Since its inception in 1997, the technical documentation department has come a long way. The department’s writers and editors used Word templates to create documentation. They used style and operational guides to standardize the documentation production process as well as to standardize the look and the message in its product documentation.

In 2002, the department was made up of the following employees:

• Two managers with FrameMaker experience who had been with the company for a while
• A Lead System Developer who had six years of experience with FrameMaker and only six months of experience at the company
• Three writers who had FrameMaker experience and had been with the company for some time
• A writer who had FrameMaker and IXgen experience and who was brand new to the company
• Two editors and 11 writers without any FrameMaker experience

Clients received documentation in print and on CD ROM as PDF files. In two cases, some of the same content was used to create online help. In many cases, the same or similar content was shared with e-learning courses.

The Problem

In 2002, we found that our clients needed us to do the following:

• Tailor documents to a specific client or groups of clients, including future Advanced Convergent Platform (ACP) clients
• Provide product information to them faster
• Provide information in additional formats

Somehow, we needed to do all this without increasing staff. These client requests were key in the decision to attempt a documentation conversion.

Up to this point, when we needed to reuse information across guides or deliverables, we used a copy-and-paste method. Another deciding factor was that we were being pressured to provide custom documentation in certain cases, especially for various uses of an extensive library of XML APIs.

The last straw came when CSG announced that it would deliver a new ACP version of our standard legacy billing system. After CSG delivered that ACP code, the documentation would diverge: we would need to produce one version for legacy clients and one for ACP clients. Eventually, all clients would migrate to ACP, but it would probably take at least two years to do so.

"We were using Word to its capacity, attempting to maintain over 11,000 pages of documentation."

We were using Word to its capacity, attempting to maintain over 11,000 pages of documentation plus various release communications projects. Our Word templates were starting to crash large documents.

The Analysis

In February of 2002, CSG management analyzed what it would take for CSG to convert its library of client documentation to an application that would allow content reuse, publication of hard-copy as well as online documentation, and easy transfer to a Help application.

After checking out possible solutions, there were two that they thought would meet our needs: Arbortext and FrameMaker. After further analysis, they selected FrameMaker for the following reasons:

• The monetary cost of Arbortext was prohibitive.
• The soft costs (e.g. lengthy conversion timeline, training costs) of moving to an XML solution were also too high.
• The FrameMaker authoring tool provided a mid-range system solution including a path to more sophisticated systems in the future.
• WebWorks Publisher provided a new filter tool so that we could produce multiple deliverables from the same source material.
• FrameMaker allowed us to output our content to paper, PDF, HTML, variations of HTML, XML, and multiple Help formats.
• We had several people already on staff with the knowledge of and skills in using FrameMaker necessary to successfully convert our documentation suite.

CONVERSION

The Lead System Developer was assigned to the Conversion Lead post. He researched customization options and available plug-ins, set up the templates, and established and wrote the procedures. His time was 100% devoted to the effort. He also set up the timelines for who did what when.

"To give ourselves the time necessary to do this conversion, our management received permission to put guide updates on hold for a year."

To give ourselves the time necessary to do this conversion, our management received permission to put guide updates on hold for a year. Some of the staff (those without prior FrameMaker experience) continued to produce release communications, while other members of the staff converted the guides to FrameMaker. After the conversion, the entire department concentrated on catching up the guides to the most current code versions.

The goal of the FrameMaker Conversion Lead was to convert all existing user documentation to the new system by February 2004. The entire team was involved in at least one phase of this project, which included training the team on the new tool, developing and setting up the software templates to meet specific documentation needs, converting all product documentation to FrameMaker, analyzing every existing product guide, hand checking each converted page for quality issues, and documenting the new process.

We kicked off the actual document conversion on September 16, 2002, and completed the conversion March 18, 2003. The Conversion Lead and the conversion team accelerated the process by installing add-on tools to speed the conversion effort. The Conversion Lead did a significant amount of research and tested these tools. He customized them to meet the specific needs of the documents we were converting.

Planning

The Conversion Lead, with management’s assistance, researched and tested possible solutions starting in February, and by September, we were ready to proceed with the conversion. During this time, the Conversion Lead also wrote a conversion guide that was the crucial tool we used when training employees on the processes the department would use for the conversion and in the future.

During the planning time, management compiled a list of CSG’s current guides and prioritized them based on need and guide complexity. They placed the easier guides at the top of the list and the complex guides toward the middle. Nonessential guides were at the end of the priority list. This strategy gave the conversion team some experience with the processes on the easier guides before they had to face converting the most complex guides.

Management and the Conversion Lead conducted a very close examination of the Word template we were using so that they knew way ahead of time what the possible problems were.

Human Resources

One of the editors was responsible for planning the quality assurance (QA) test and assigning people to the QA tasks.

All the staff members were advanced Word users, so they understood the concept of using templates, document styles, writing standards, and style guides.

One of the writers who had been with CSG for some time, but did not already know FrameMaker, was the person who, with the Conversion Lead’s help, wrote the template training materials and conducted the template training.

The people with FrameMaker experience were the ones who actually did the bulk of the conversion.

After we were trained, each employee without prior FrameMaker experience was assigned to one of the three experienced writers, who acted as mentors and trainers.

Training

The managers made training our top priority.

First, we were told to take ourselves through the Adobe FrameMaker Classroom in a Book course before a certain date, which was the day of our in-class training.

Second, CSG contracted Sarah S. O’Keefe (who co-wrote The Complete Reference FrameMaker 7 book) to conduct stand-up training in Omaha. Before arriving, she had already seen our documentation templates, so she knew how we were going to use FrameMaker.

Third, we received training specific to our templates and our new processes.

Finally, when we began the conversion, the Conversion Lead created a library of FrameMaker questions, answers, and tips. He made this library available to us through our department’s internal Web site. As the questions came in, he answered them and published the resolutions on the site. He later added a subject index and search capabilities to the library.

"Finally, when we began the conversion, the Conversion Lead created a library of FrameMaker questions, answers, and tips."

Tracking

The Conversion Lead and management created the following forms that we used to track our progress and log issues:

• A planning form, which we used during the analysis phase of the conversion to analyze the contents of each guide and determine any special issues to watch out for during the document’s conversion. After completing the form, we met with management and the Conversion Lead to discuss the contents of the guide.
• A quality check form, which we used to log issues that we found in the converted documents during the quality check.
• A project status report form, which we used to track and update tasks, log issues, and log suggestions.
• A document analysis form, which we used to log issues and create a wish list of things we would like to see in the guide in the future.

The Conversion Lead reviewed the issues list at least twice a day. When he established resolutions, he added them to the spreadsheet for everyone to review and, if relevant, added the item to the question/answer library.

Plug-Ins and Customization

"The experienced writers helped automate the conversion by recommending automated solutions for repetitive tasks."

The Conversion Lead was motivated to automate as much of the conversion as possible. The experienced writers helped with this effort by recommending automated solutions for repetitive tasks.

As part of the analysis phase, the Conversion Lead conducted research into what plug-ins CSG should purchase in addition to FrameMaker. After his analysis, he and management agreed to purchase the following plug-ins:

Paragraph Tools

This plug-in maps Word styles to FrameMaker paragraph styles.
www.siliconprairiesoftware.com

TableCleaner

This plug-in cleans up the tables that come over from Word.
www.frameexpert.com

Master Page Tools

This plug-in finds all pages, even those containing tables (unlike FrameMaker’s master page tool utility).
www.siliconprairiesoftware.com

Auto-Text plug-in

This plug-in allows you to define a set of text or graphic items and insert them into FrameMaker.
www.siliconprairiesoftware.com

IXgen

This plug-in helps you create and edit indexes.
www.fsatools.com

The Conversion Lead also did the following:

• Learned FrameScript so that he could create other scripts that would help to automate some of the conversion process
• Customized FrameMaker by removing some toolbar and key commands that might have confused Word users (e.g., bold, underline)

Conversion Guide

The Conversion Lead wrote a conversion guide that contained the processes that he and management had established for writing and updating our documentation. Management made it mandatory that everyone read through the conversion guide prior to or just after template training.

The Process

The Conversion Lead established and tested the following conversion process and included it in the conversion guide. This is the process that we followed for each of the guides we converted:

1. Set up
• The workspace
• The FrameScript environment
2. Prepare the Word file
• Graphics
• Remove unnecessary elements
3. Import the file
• Create a new FrameMaker document
• Import the Word file
• Import an RTF version of the Word file
4. Clean up the document
• Map paragraph tags
• Map character tags
• Fix tables
• Remove cross-reference markers
• Map master pages
• Page through the document
• Fix graphics
5. Do post-conversion clean-up

RESULTS

"We converted 11,677 pages of documentation from Word to FrameMaker in six months. The total time spent on this project was 4,106 hours."

With a total of 20 staff members, we successfully converted 11,677 pages of software application documentation from Word to FrameMaker in six months. The total time spent on this project was 4,106 hours.

By completing this conversion, the department now produces its documentation more efficiently. Converting also allows us to produce documentation for specific customer needs, including ACP product documentation.

The conversion process allowed the team to build additional functionality into the technical documentation library CD-ROM and online help deliverables.

A bonus result of the conversion is that we were able to start providing clients with complete user documentation and bulletin information prior to a major software release. Prior to the conversion, clients received user documentation updates 4-6 weeks after a release.

LESSONS LEARNED

What went right, and what could have gone better with the conversion? To get the answers to those questions, I interviewed the staff members who are still with the company. Their responses follow.

What Went Right

Staff members thought we did the following things right:

• Planning
• Training
• Using automated scripts and plug-ins
• Assigning a dedicated conversion team

Planning

It is the consensus of the group that the amount of planning time before the conversion began was key to the success of this project. Everyone thought the conversion was very well planned out.

"It is the consensus of the group that the amount of planning time before the conversion began was key to the success of this project."

We started the conversion effort with the easy guides. The conversion was done in stages: first the text, then the graphics.

From the technical perspective, we were already using styles and document templates in Word, so writers were already used to working with them, and because they had worked with them so diligently, we found few errors when converting from a Word style to a FrameMaker paragraph tag.

We had great leadership on this project. They made sure that we were all on the same page.

When we converted the documents, we were restricted from doing any editing. The task was to convert, not edit or rewrite. If things were really bad in a particular guide, we noted the problem in the issues log and moved on. Our motto was convert first, clean up later.

Training

Between all employees walking through the Classroom in a Book course by themselves, attending Sarah’s FrameMaker training, and attending the template training, most employees thought they were well prepared to use the new tool.

The conversion guide was another key to our success. It was very helpful, both in training staff and during the conversion.

Automated Scripts and Plug-Ins

Automation helped us to convert the documents quickly.

If the templates were used in Word, then the conversion worked well. Because the Word templates were fairly strictly adhered to, the conversion was successful.

The custom scripts helped a great deal; they made the process much smoother and everything was done more quickly than other conversions one writer had experienced previously.

Short-cut keys and macros substantially cut down on the amount of work.

Dedicated Conversion Team

Starting out with just three people doing the conversion, and then testing the process, was good too.

It was a good idea to split up the staff into those who were 100% dedicated to the conversion and those who kept up with the release communications for the products.

We were able to keep the management and staff we had throughout the entire process. We did not lose any experienced folks prior to completing the conversion, so we reaped the benefit of retaining knowledgeable people.

Without teamwork, the project could not have been completed so successfully. Every member of the team was involved in one way or another.

"Without teamwork, the project could not have been completed so successfully. Every member of the team was involved in one way or another."

What Could Have Gone Better

The Conversion Lead would have liked to have had more QA afterward because we never got all the guides through QA toward the end.

We communicated a great deal between members of the group, but communication became unwieldy. We needed to attend many meetings to discuss processes, etc., and these meetings took us away from the conversion work. We attempted to solve the “meeting” issue by breaking the department into three groups. Each of these groups elected one lead representative. This person met with management once a week and took information back to the other members of his or her group. We also kept meeting minutes to disseminate changes, tweak the processes, and stay on top of the status of our projects.

We should have created a return on investment (ROI) analysis for this process, but we never did.

One person on the conversion team said that the conversion team needed more training up front because the Conversion Lead was hammered with questions all the time. Even though they had the conversion guide, they still had questions.

Another writer would have more radically changed the style of the guide when we did the conversion. There’s a lot of similarity between the Word and FrameMaker documents. She would have liked the FrameMaker documents to look different from the Word versions. She would also have liked to see more people use IXgen. We should have done a better job of promoting the use of IXgen as a time-saving tool.

What did we sacrifice going to FrameMaker? Sharing documents between departments. Our subject matter experts (SMEs) must now review drafts as PDF files, rather than using the track changes feature in Word.

Screen shots and tables were issues with the converted documents. We spent quite a bit of time attempting to determine the best DPI for the graphics in our FrameMaker files.

We needed to reduce the stress of converting documents all day long.

We overplanned the time it would take for us to complete the conversion.

Have people sit closer to each other so they can communicate easily.

Keep morale in mind. Make sure that everybody on the team is on board with the changes and that people aren’t sabotaging the group’s morale.

Establish the standards prior to the whole conversion. Try to reduce the number of things that are going to change, especially before bringing in the entire staff.

Some of the people with no FrameMaker experience were very nervous about the conversion and worried that the conversion would impair their ability to perform their jobs.

Deb Lockwood
Lead Documentation Writer
CSG Systems, Inc.
11080 CirclePoint Road, Suite 300
Westminster, CO, 80020, U.S.A.
303-280-6522

Deb is a Lead Documentation Writer at CSG Systems, Inc. (www.csgsystems.com). She is a member of the Rocky Mountain STC chapter, where she serves as the Treasurer, Mentoring Committee Manager, and contributor to the chapter’s online newsletter, Technicalities. She is also a member of the Consulting and Independent Contracting and Lone Writer Special Interest Groups. Deb has an MSS in applied communication from the University of Denver and a BS in management from Regis University.