Publishing on CD-ROM: Converting Paper Documentation to a New Medium News & Views Feature Article

by Prescott Williams, Documentation Manager, and Catherine Alexander, Associate Technical Editor Soft-Switch (Chesterbrook, Pennsylvania) Originally published in News & Views November, 1996 issue. Copyright 1996 STC-Philadelphia Metro Chapter. For permission to reprint this article, contact the Managing Editor.

Consider this a progress report. Early this year, as part of a corporate refocus, Soft-Switch management made a commitment to better support for our products, including improvements to our documentation. Much of that commitment has gone toward better content, but we are improving our delivery as well, specifically by distribution on CD-ROM in addition to paper. This article recounts our experience in the early part of the project. Our various audiences had made it clear they were not satisfied with the old method of distribution. Our end users, network and mail system administrators, were accustomed to manual sets of thousands of pages packaged by Interleaf or the IBM Bookshelf, for example. Demand came from internal customers as well. Support analysts need to respond quickly to customer problems. Installers cannot possibly carry all the manuals they might need when they're on the spot at a customer site. Goals and criteria One goal was to publish our manuals on CD without losing any of the navigational aids our users had when they were working with a paper manual. That is, they had to be able to scan the document easily and to use the table of contents (TOC) and index at least as easily as they could in a paper document. If possible, we wanted to go at least one step beyond paper delivery by providing some sort of search capability. Graphics were another issue in our transition to CD. The delivery vehicle had to support graphics from several different sources, including PowerPoint, Freelance, Microsoft Draw, Paint Shop Pro, and bitmapped screen captures. We did not want to sacrifice any special formatting of tables, charts, or procedures. Another goal of CD publication was to shorten our documentation cycle. We wanted to improve the content of our manuals to reflect last-minute enhancements, bug fixes, known problems, installation hints and tips, and other late-breaking developments. Despite our plans to move to CD, we had to continue to distribute our documentation on paper. While CD drives are becoming part of the standard desktop configuration, we could not assume that every user could use a CD. Equally important, we were not starting from scratch. We had approximately 100 active manuals. Since our source material was in more than one format, we knew we would have to do a considerable amount of document format conversion. We needed a tool that had effective filters so that we would not face weeks of cleanup and hand formatting after conversion. Portability was essential. Our legacy documents had been created on several different platforms. We had a total of approximately 15,000 pages, mostly in Word for Windows, but more recent releases were in AmiPro. Additionally, we support products running on 3 flavors of UNIX, Windows 3.1, 95, and NT, OS/2, and MVS and VM operating systems. The biggest constraint in meeting these goals was a lack of staffing and time. Our very small staff had to continue to meet commitments to support ongoing product releases. We had to choose tools and procedures that were simple, easy to learn, and robust. Selecting a tool We examined several manual sets published on CD, but when we looked into how they were produced, we found that while the documentation platforms were quite powerful, they often required complex document assembly procedures, version control, and a long learning curve for authors. Given these considerations, we settled on the Adobe Acrobat Portable Document Format (PDF) as our delivery format. The basic procedure in using the Acrobat package begins with a document in PostScript. You then run the document through Acrobat Distiller. This gives you an electronic representation of the printed document. The text and graphics appear on pages that match the printed copy. Because the electronic copy matches printed copy, the TOC page references and the index citations are still correct, as are cross-references within the document. With the Acrobat Reader (which you can distribute free with your document), users can page through the document with Page Up and Page Down keys or use a thumbnail view and a vertical scroll bar to get to a specific page. Using FrameMaker files as input to the Distiller lets you avoid the labor of rebuilding the TOC and index connections after the distilling process. After FrameMaker files are printed to PostScript and run through the Distiller, the resulting PDF file contains hypertext links between the TOC, index, and the body of the document. This saves you the step of having to manually link each TOC and index item in the PDF file -- a very tedious task we were happy to avoid. Opportunities and complexitites As we began to discuss our plans with Adobe in detail, we learned a couple of things we had not anticipated at the beginning. While they opened new opportunities for us to meet or even exceed our initial goals, they opened up some additional complexities as well. The Adobe Catalog product builds an index of a set of documents, enabling full-text search of the contents. (Adobe charges a fee, however, if you want to distribute documents with capabilities beyond the simple Reader.) Another surprise was a capability of PDF links. You can enter a World Wide Web Universal Resource Locator (URL) as a link from a hot spot in the PDF document. Since we already publish last-minute release information in memos that appear on the Web, most of our customers will be able to get to the latest information directly from our manuals. Choose the URL with care, however; if your Web site is in transition and someone changes the URL, you run the danger of a hot link that goes nowhere. To avoid complete relinking with every release, we decided to try FrameMaker; now we were confronted with the challenge of taking our existing documentation and converting it into FrameMaker format. It soon became apparent that it was too much to publish everything in the first release. Our pilot release will carry a limited set of manuals, but they will be for our latest, highest-visibility products. We had to go through a "triage" process to assign priority. Conversion Our first stumbling block in the conversion process was the fact that we could not open, import or otherwise view AmiPro documents in FrameMaker -- the files were considered "Unknown File Types." We spent hours trying to bring these files into FrameMaker, with very little success. Eventually, through much trial and error, we found two solutions to this problem. The first was to go back into AmiPro and re-save our documents in Rich Text Format (RTF). Once in this format, the documents were brought easily into FrameMaker, retaining style formatting and the majority of screen captures and figures. One major defect of this process was index markers -- they simply disappeared in the conversion. The second solution to our conversion problem was an Adobe file conversion utility called Word for Word. Its conversions retained all formatting and graphics from the original file. The best news for us: it retained index markers in the transition to FrameMaker. Once the files were in a format readable by FrameMaker, the next step in the conversion process was to create FrameMaker templates that met Lotus style requirements. Creating these templates meant duplicating the paragraph styles, footers, column definitions and other page layout elements of our AmiPro stylesheets. Considering our inexperience with FrameMaker, we considered this step to be one of the most challenging aspects of our platform transition; it took one person working full-time for a week to complete our customized templates. With the completion of the templates, our document files were neatly converted to FrameMaker format. Putting the parts together It was now time to start the actual process of pulling the separate parts of the documents together. This was done by generating a FrameMaker "book" file and printing it to a PostScript file. At this time "Acrobat Data" was generated -- automatically creating the hypertext links in the Table of Contents and Index in the PDF file. Once the PostScript file was created, it was converted to PDF through the Acrobat Distiller. When we tried to distill our FrameMaker PostScript files, however, we continually received PostScript errors and were unable to generate the PDF file. At the time we were using a generic PostScript printer driver to create our PostScript files, but this was incompatible with the Acrobat Distiller. Finally, after testing one printer driver after another, we found one that worked perfectly -- the Linotronic 530. Our book files were now easily printed to PostScript, distilled, converted into PDF and readable in Adobe Exchange. Creating the interface The last major part of the project has been creating the interface to the CD contents. Our method consists of a set of FrameMaker files that give an overview of the document sets and how they are categorized, a listing of every title for each product group, instructions on navigation, and some general corporate information. We found that separate files for each type of information gave us more flexibility to both get the user oriented and then direct him/her quickly to the required documents. Today we are about a month away from distributing our pilot CD. We are still struggling with issues of platforms, usability, and aesthetics. With each demo of our material, new suggestions and challenges have surfaced. For example, it didn't take us long to realize that images represented on our 21-inch monitors look very different on 14- or 15-inch screens. Needless to say, that issue made us re-think the layout of many of our interface pages. This issue, and many others, have literally sent us back to the FrameMaker drawing board several times over the past few weeks. With each change, however, we are making a step forward. This is, after all, a work in progress.

Return to . . .

[News & Views] [STC-PMC Home] [STC Home Page]
Last updated: November 29, 1996 (rst)