Interleaf: Smart Software for Multimedia Documentation Delivery News & Views Software Review

by Bev Bruns Bev Bruns is a Marcom Program Manager with Hewlett-Packard Company in Wilmington, DE 19808-1610 and by Dave Harkins Dave Harkins is a Senior Analyst with Kinetic Technologies, Inc., 1964 Gallows Road, Suite 210, Vienna, VA 22182. 703-883-1898 Originally published in News & Views November 1998 issue. Copyright 1998 STC-Philadelphia Metro Chapter. For permission to reprint this article, contact the Managing Editor.

Modular Planning for Multimedia Delivery (B. Bruns) Introduction We hear it over and over again and the message is crystal clear: Many of the documents we create will end up in a variety of places: Hardcopy, CD's, inter/intra/extranets, corporate databases. Many of the documents we develop may require technical drawings, or charts, or scientific materials from preexisting company documents. Much of the information contained in the materials we produce will be reused in revised formats over and over again for indefinite periods of time. This includes hardcopy and online updates of documents such as order guides, catalogs, technical manuals, and a variety of applications such as user guides, quick reference guides, promotional brochures, etc. It also includes regular periodic revisions of web sites. And, if your company sells globally, another important component of document delivery planning is the need to translate or localize your materials into multiple languages - and keep those documents updated and revised. It's clear that this is no longer a game for wimps. If you are the lead tech writer, managing editor, or marketing communications planner for your group, your responsibilities have escalated considerably and the choices you make can have a walloping impact on your company's bottom line. Best Practices The first thing you have to do is recognize that-if your company provides a wide variety of documentation-you will probably end up using more than one type of software to get the job done. Direct Marketing: Many direct marketing pieces, one time flyers or mailers for special promotions, will go to external agencies who will inevitably deliver in Quark Xpress or Adobe PageMaker. Since these materials often have a limited life span, don't include information that customers need to retain over a long period of time, and are usually small, Quark or Pagemaker or any similar desktop publishing system is just fine. Sales Materials: This is an interesting category. Often the domain of the marketing department, sales materials can include technical notes, catalogs, order guides, and other flora and fauna of technical product-specific information focused for product sales and customer use. Training materials, presentations, and technical support information can also fall into this category. Many of these are core information-critical, long lifetime documents. Technical Manuals and User Guides: Long the workhorse units for long-term, information critical, reused documentation. Much of the long-term, core data, such as training materials, technical manuals, and catalogs, includes information that will be reused over the course of many years, will require regular updates, will often be delivered to the web, may be copied to CD, and will be delivered to the printer electronically (PDF files). Clearly these deliverables are most efficiently and economically created on a database publishing system like Interleaf. Such systems permit: Speedy updating Data/information chunking and reuse Delivery to both SGML, HTML, and XML media Automated indexing, pagination Automatic revisions cross-documents Multiple search capabilities Delivery of information to multiple formats concurrently Creation of one manual for delivery to trainers and customers Delivery to a database It's important to remember that-in this age of multimedia delivery-the type of software you use can either greatly enhance or hinder the efficiency and cost effectiveness of your communications group. Very seldom do companies take the time to effectively cost factor the efficiencies of having critical and core documentation on the same database, and the use of digital publishing web editors, storage, and linking capabilities available all in one system. In addition, very often the people charged with making decisions about communications tools are not communicators and are not familiar with the full range of activities required to produce, publish, and store one document. As end users and customer advocates, professional communicators need to be in the forefront of the tool selection process. When it comes to software tools selection we are, in fact the critical decision-makers for the quality and usability of the documentation we create. Modular Data Development Annual communications deliverables plans should include an assessment of which components of available publication media should be selected for each document created; how those components will work together; how they will work with your current system; and how they will be maintained and stored. Once you have established the most appropriate customer contact media for your communications mix, you can begin to think about how best to develop information that: Is intuitive and easy for customers to use Can be neatly and easily transported among multiple document formats Will provide an effective cross-marketing presentation (i.e., suitable for multiple types of documentation, scales easily, etc.) Modular delivery involves thinking about how much of the information you produce can be simplified and retained in "modules" such as clearly understood charts, tables, insert segments, examples, etc. People don't have time to read - they want to be able to go to a resource and get the information they need as quickly as possible. Repeated surveys show that business customers and everyday readers prefer their information in hard copy. This is especially true of long-term use, every-day information resources like procedures, operating information, user guides, and catalogs. The idea of the "paperless" office has been advocated by many. But hardcopy is here to stay. While electronic format provides different benefits, like interaction, ordering, and instant worldwide updating, it still takes less time to pick up a catalog and find the entry than to pick through a series of URLs on an already running computer. As we move closer to voice commands, it may become much easier to tell your computer to access documents for you, in which case, using your computer for these types of materials would make more sense than using hardcopy. But users would still miss the benefits of thumbing through a paper document which includes finding ancillary information and products of interest on the way to the item of immediate interest. Developing modular data documents will provide you with information components that can work effectively within the design constraints of a variety of media. Modular information can also be updated, replaced or revised easily. It is, in essence, the idea of working, as much as possible, in "object-oriented" data mode. Once you have a good repository of modular data, you will begin to save time and resources reusing material to create new documents. Software Tools Because many professional writers, editors, and graphic artists have minimal training as computer experts, we tend to know how to use whatever has been imposed on us from internal or external sources. And, as the software systems and choices proliferate, often paving paths of obsolescence for software currently in use, it becomes more and more important for us to make smart strategic decisions about how we deliver our information. And that means we need to have some basic understanding of what tools are available and how best to develop information that will be delivered to multiple media. Software selection is really central to every aspect of documentation planning and delivery. Poor software selection can result in ineffectual production, delivery, and processing of documentation for multimedia presentation with the negative payback of: Lost opportunities due to late or missed product delivery dates Massive cost overruns due to reprocessing requirements Decreased productivity Loss of department dollars to deliver full marketing programs And the ultimate ignominy of delivery of inferior products to customers. Looking at the absence of an electronic document distribution (EDD) or electronic document management system is another way to examine the potential for achieving best practices. How many documents are linked (i.e. contain information on the same subject?) How often do you reprocess information, moving it from one format and presentation mode to another? Does it have to be recreated from the ground up every time? Can you track revisions made to your documents? What are the manpower resources in your group? Do you and your colleagues spend quality time trying to figure out how to get Freelance, PowerPoint, and Quark Xpress together into a newly created document? Do you work with a variety of vendors who create non-revisable documents? Would it be helpful to have these documents linked for mix and match delivery to new documents or the web? These are just as few of the components of development and delivery that should be assessed before you can determine the most efficient and effective way to create and distribute information to your customers and a corporate database. The one electronic publishing system that has remained constant in my work horizon over the past ten years is Interleaf. Like the rest of the industry, this electronic document distribution (EDD) system has come a long way. The company has evolved and managed to stay ahead of the technology curve. The Interleaf Technical Publishing System (TPS, now commonly know as just "Interleaf") is one component of a powerful suite of products that is cross-platform (DOS, Windows 95/98, Windows NT, and UNIX) and includes the tools needed for multimedia delivery. I currently produce a variety of smaller customer-focused marketing documents instead of editing longer technical papers or writing technical manuals, but I've stuck with Interleaf because I know what it can do. Over the past few years I've used Interleaf to take the same catalog to the printer, the internet (using their web editor, Cyberleaf), and CD-ROMs-all in record time and cost effectively. Maintaining smaller marketing documents on the same database is easy to do and helps me be twice as efficient because I can retrieve, mix and match (chunk), update, and modify data quickly. This is especially useful when creating several versions of the same document for delivery to different segments of a customer base; or when updating and revising complicated documents like catalogs. The cataloging, formatting, data linking, and editing components of this powerful and constantly evolving electronic data delivery system make it my primary productivity tool. The person I have worked steadily with over the past seven years is documentation specialist and Interleaf expert, Dave Harkins. Dave keeps current with emerging software tools and maintains a "comparative shopping list" of features and capabilities available from a variety of software authoring tools. Interleaf: An EDD for All Seasons (D. Harkins) Philosophy 101 Interleaf is an electronic publishing system that combines all aspects of the documentation process into one package. This EDD offers tremendous flexibility and power to users through a collection of features, the most important of which is its integrated file and template management system. This is not the place to discuss detailed descriptions of everything that Interleaf does, particularly with regard to features found in other electronic publishing tools, like indexing and cross-referencing, except to point out that Interleaf has such capabilities too, and to draw attention to any particular strength which Interleaf has in the area concerned. The focus here will be to identify some of the special features and capabilities of this powerful system. Interleaf is not a panacea. However, it is the closest thing to a paragon of electronic publishing currently available anywhere. Sadly, it seems to be a staple of our industry that the best tool for every job just happens to be "the tool I or my favorite vendor am most familiar with". While there are a lot of great publishing tools out there, the key to best practices is knowing the strengths and limitations of each, and using them to their best advantage. In the quest to find something "we can do everything in," I have seen large (100+ page) manuals done in word processors. Word processors are wonderful things, but they are just that, word processors, no matter how many bells and whistles get added to them over the years. Those who have people that "can do anything with (fill in word processor of choice here)", be warned. Maybe the person in question can do anything with a particular program, but given smart software, the same individual could take the time they currently spend tweaking inadequate publishing resources, to greatly boost productivity and quality while delivering to multimedia. The end result would be better quality and higher productivity with noticeable savings in time and money. We are currently still in a "market in which highly advanced technology is viewed as a commodity precisely because nobody much is using the stuff. (1)" So let's take a look at what constitutes one "advanced technology" software system, and examine what it can do for you and your document delivery capabilities. The Publishing System Interleaf is multi-platform and can be installed locally or on a server. It is available in several languages including German, French, and Japanese. At one time, only operating systems like UNIX had the capacity to handle the extremely large files that Interleaf is capable of creating. That is no longer the case. Starting with Interleaf 5 for DOS, Interleaf has gradually expanded into the Microsoft operating system environment. The current state of the art is Interleaf 6.3 for Windows 95, with Interleaf 7 due later this year. Interleaf can import and export a wide variety of text and graphics formats including Microsoft Word Rich Text Format (RTF) and Corel WordPerfect for text, and Computer Graphics Metafiles (CGM) and Tagged Image Format (TIF) files for graphics. Note: A word about importing and exporting. Very few, if any, program translations are 100%. When going from basic programs to programs with more advanced features, there is usually very little difficulty. However, when moving data from more advanced programs to basic level programs, something is inevitably lost. This is not a commentary on either level program; it just stands to reason that sophisticated software will be able to absorb less complicated programs but the reverse cannot be expected. When losing some features, the resulting document is unlikely to appear just like it did in the higher end application. The same is true for graphics. File Management The heart of Interleaf is its integral file management system, the Interleaf Desktop. Using the Interleaf Desktop, one can cut and paste or drag and drop icons representing all of the elements that make up Interleaf books and collections to achieve a power, flexibility, and ease of use unrivaled in any other system. Especially with the advent of Interleaf 6, the interface now has much in common with many other Windows-based programs. Figure 1 illustrates the Interleaf Desktop. In the upper left are several basic desktop components like the clipboard and the System6 cabinet. To the right are some representative icons, the nature of which will be discussed shortly. Figure 1: The Interleaf Desktop Standard Components Like almost all programs that deal with documentation, Interleaf possesses automatic table of contents generation, indexing, running headers, cross-references, an equation editor, tables, and style definitions. It also has extensive graphics capabilities, which allow you to draw isometrically with features, like bezier curves and named graphic objects. The latter allows you to draw something, group it, name it, and then create new instances of it with a menu command, eliminating the need to go back and copy the object. While some of these features may be better in Interleaf, or at least equivalent to the corresponding features in other systems, it is in conjunction with Interleaf books and catalogs that they really come into their own. Catalogs Interleaf catalogs have capabilities unmatched in any word processor, desktop publisher, or other electronic publishing system. Catalogs function within Interleaf books, a special type of folder. Within books, documents can generate TOCs and indexes, inherit formatting data from catalogs, and be linked to any number of other books. Catalogs are very similar to the templates available in many programs but with powerful enhancements. Create a good catalog, and Interleaf will do most of the formatting for you. Example: If you were creating a 600-page catalog and had to pull out six pages two days before press time, that's almost all you would have to do. Interleaf would flip/convert left and right pages; repaginate the document; and correct cross-references. You could then regenerate the index and table of contents in seconds and format them in almost no time with the aid of the appropriate catalog. There is an active, live relationship between a document and any catalog(s) exporting to it. Within an Interleaf book, any number of catalogs may shape a document or documents at the same time. Example: A manual may derive its style definitions from one catalog, its page layout from another, and its headers and footers from yet another. Conversely, it can also derive everything it needs from just one catalog, whatever option best suits the needs in question. The documents (engine and suspension) in the book in Figure 2 will inherit their formatting information from the catalog to their left. Figure 2: An Interleaf book with one catalog and two documents Document Control and Security By maintaining all of the catalogs for all of the types of documents you produce in one central location accessible to all users, the catalogs placed in the books described above can be links (shortcuts) instead of copies. Aside from saving storage space, this practice guarantees that all documents meant to comply with a particular format, are actively linked back to the catalog for that format. If a logo in a header or the wording in a copyright statement is changed in the catalog, all documents being shaped by that catalog automatically and instantly reflect the change with no additional input from the operator. Organizations can also maintain a high level of control to ensure document consistency. The catalogs can be protected at their source against unauthorized users. By doing this, only modifications that have been thoroughly debated and approved by authorized personnel can be implemented. A catalog link behaves just like any other file on the Interleaf Desktop. Link names are italicized to remind the operator that they are links (notice that the catalog in Figure 2 is a link). A link merely needs to be placed within a book in front of the documents it is intended to shape for it to do its job. A catalog link can export headers/footers, frames, graphics, auto-numbers, components (styles), tables, and document/page number properties in any combination desired. In this way, Interleaf is much like SGML/XML, which is the key to future e-commerce. SGML/XML is concerned with structure, not format. Format is obtained by style sheets in whatever viewer is being used. The same principles apply here. The Interleaf document is the content; the catalog is the style sheet. Nevertheless, Interleaf is still an electronic publishing system. If a document is divorced from its catalog, it has a copy of that catalog's definitions built in, so it could still be readily opened and edited. Place it in front of another catalog that uses the same definition names but has a different appearance, and the document will take on the new look. Save the document under the new circumstances and the new catalog will become its new built-in set of definitions. Sequencing Using Interleaf's extremely flexible auto-numbers for section numbers, lists, figure numbers, and table numbers, allows a book to be re-sequenced by simply rearranging the order of the documents with the file manager. In addition, books done using the same catalogs can easily exchange chapters. Example: If the documents in Figure 2 are numbered, currently, engine would be section 1 and suspension would be section 2. Simply moving the engine document after the suspension document would automatically make the engine document section 2 and the suspension document section 1. Done correctly, this would also include the figure and table numbers that reflect the section number (e.g. Figure 1-2 or Table 2-4). Virtual Documents: Multiple Versions Using the practices described above, and linking documents as well as templates, any number of different versions of a document can be created. Every version would use the same document file but different catalogs. A modification in one version changes all versions because all the documents are merely links back to the main version. It should be stated at this point that links are bi-directional. Open the link, and you're opening the file. This does not endanger catalogs if they've been properly protected against unauthorized users as previously described. Example: The most obvious application of this principle is a situation where you want a print version and an online version of the same information. Perhaps a portrait, two-column, black & white version is needed for printing, and a landscape, one-column, color version is needed for electronic distribution with something like Adobe Acrobat or Interleaf WorldView. As illustrated in Figure 3, you would have two separate catalogs and books - one for each version. You then create the document in either book (the main document is in the Print book in this example), and merely create a link (note the italicized name) to the same main document in the other book (the Online book in Figure 3). If you open the document from within the Print book, it will look one way. If you open the document from within the online book, it will look entirely different, but the data will be the same. Delete a paragraph in one and you're deleting it in the other. Figure 3: Books for two versions of the same document The main document need not even exist in one of the books. It could be stored elsewhere and linked to in both cases. Interleaf can handle both the simple and complex with equal ease. It all depends on your requirements, both current and future. To go even further, an entire book may be a link. For example, a book concerning engine repair may appear in many different manuals for many different pieces of equipment which all use the same engine. Redundant copies do not have to be created. The engine repair book can be linked into as many different master books as necessary. By constructing a body of documents as a group of sub-books within a master-book, auto-references (cross-references) can dynamically ensure that if Figure 3 becomes Figure 2 because Figure 1 was deleted, any text along the lines of "see Figure 3" will become "see Figure 2" automatically, even in other books. Effectivity In Interleaf, effectivity refers to tagging elements so that only certain ones will appear in a given version. In this case, version refers to the content of a document, not the format as explained in the Multiple Versions section above. Example: The best way to explain this is to think of teacher and student versions of a training manual. Within the same Interleaf document, the elements which contain anything the students should not see, can be tagged to appear only when the teacher version is displayed. Two documents do not need to be maintained. The operator simply calls up the desired version from within one document. Once again, changes made to one version are automatically made to the other because they are one and the same. Interleaf automatically repaginates. Text Import As already mentioned, Interleaf can import many types of text files. Writers can use their favorite word processor (Word, AmiPro, Word Perfect, etc.) without worrying about format. If a writer simply uses the style names defined in the corresponding Interleaf catalog, and does not manually override style definitions, Interleaf will automatically do the bulk of the formatting upon import and placement next to the appropriate catalog (see Figure 2). Revision bars and index tokens are also retained when imported into Interleaf. Distribution Options Interleaf documents can be distributed in a number of ways. In addition to traditional and on-demand printing, several forms of electronic distribution are available. Interleaf WorldView is a very powerful viewing program. It resembles Adobe Acrobat in that it displays the pages as they appear in the Interleaf publishing system. However, using the practices outlined in this article, a version of a document could be created which was targeted for a web environment. Also, drawings that are vector in the Interleaf file will be sharp as a tack in WorldView no matter how far you zoom in. WorldView also possesses very advanced searching capabilities. Interleaf Cyberleaf converts Interleaf files into HTML for the World Wide Web. Interleaf can also create a post-script file that, when run through Adobe's Acrobat Distiller, creates a fully functional PDF (Portable Document Format) file that can be distributed using Adobe's very popular Acrobat Reader, or sent out for high-end printing (see below). As Interleaf is a founding member of SGML Open, an organization to promote the worldwide adoption of SGML, Interleaf products are very SGML-friendly. SGML documents can be created by running Interleaf files through SGML converters such as INSO's DynaTag, or by using Interleaf 6 SGML. The same can be said for XML, basically SGML renamed. Interleaf is currently developing its own product for XML distribution (currently called BladeRunner) in conjunction with MicroStar, leaders in SGML/XML technology. In all of the cases above, cross-references and hyperlinks (created with Interleaf's Hyperleaf) can be automatically converted to "hot spots." These hot spots can be clicked on in any of the viewers mentioned, including Acrobat, to take the reader to the page on which the paragraph, figure, or table being mentioned appears. High-end Printing A word about high-end (or commercial) printing. PDF is currently the future of commercial printing. The Adobe Acrobat Distiller can be configured to produce high-resolution PDF files suitable for high-end printing use. The days of unstable, massive post-script (PS) files will soon be gone. This is significant because of some of the things Interleaf does not currently do. Programs like Quark Xpress and Adobe PageMaker were created for the marketing/advertising business. They do produce color separations and bleed as a matter of course; Interleaf does not. However, Interleaf is now Pantone Calibrated and can do spot color separations. With the advent of the Acrobat's high-end capabilities and products like Lantana's Crackerjack, the native file for an application is becoming irrelevant from a high-end printing perspective. Crackerjack, for instance, produces color separations from a PDF file (2). I mention this because, while Interleaf was originally created for large, black and white technical manuals back in the late 70s/early 80s, its current color capabilities, combined with Acrobat and Crackerjack, make it a viable vehicle for smaller, marketing types of documents (I've done countless such pieces over the years). This is where knowing what you're talking about concerning software selection really matters. If your documentation needs span a wide variety of types of documents and you want one primary tool capable of handling 4 to 40,000 page documents, Interleaf may be for you. You may still use other applications for specific jobs, it would be foolish not to, but the value of having one extremely capable repository in which data can be mixed and matched, reused, and distributed, easily and at will, can not be overestimated. Conclusion At the outset of this article, I said that Interleaf was not a panacea. Neither is it magic. It can go a long way toward solving an organization's documentation needs, but rules and procedures must be followed if the real strengths of Interleaf, or any other program for that matter, are to be realized. Structure, real (SGML/XML) or even implied (desktop publishers), is the key to documentation flexibility. Every time operators are allowed to use software any way they desire, rather than the most efficient and appropriate way, time and more importantly, money is wasted. Every time a document is created in a program which uses one style name and the author just highlights the text and changes its properties to get the desired appearance, or plops text into graphic frames, the end result is going to be the expenditure of more time than is warranted to create a finitely useful chunk of information. So before you decide on any publishing package, please, do your homework. For more information on Interleaf, go to www.ileaf.com. (1) Blurb from 1997 CAPV Ventures Seminar mailer. For more information on CAP V see www.capv.com (2) "PDF Printing and Publishing: The Next Revolution After Guttenberg" Frank Romano (founder of the magazine Electronic Publishing).

Return to . . .

[News & Views] [STC-PMC Home] [STC Home Page]
Posted November 10, 1998 (dls)