September 2002 meeting review: single-source publishing with FrameMaker

by Linda Gallagher and Joel Meier

Martin Smith, the creator of VersiText, a help-authoring tool for structured FrameMaker documents, demonstrated how you could use FrameMaker to create single-source documentation for multiple audiences. Martin writes and organizes the information in FrameMaker. He then uses FrameMaker to publish his standard print documentation and VersiText to "cherry pick" information and publish his online versions.

With the release of FrameMaker version 7.0, Adobe has combined the features of standard FrameMaker and FrameMaker+SGML (used to create structured documents) into a single product. Using the structured functions of FrameMaker 7.0, Martin demonstrated how you can use structured documents and VersiText to produce totally different outputs for your printed and online documentation sets.

Structured documents, such as those created using SGML, have a reputation for being both a complex and an expensive way to manage information. However, Martin made it look fairly easy. Using an Element Definition Document (EDD), FrameMaker 7.0, and VersiText allows you to organize and reorganize the structure of your information. 

The key to implementing this method is creating an EDD that contains all of the documentation elements you need and structures them appropriately for your outputs. This process requires a thorough analysis of your users, their needs, documentation content, and more. Martin then customizes VersiText as needed to 
produce the online output in the format and using the structure you require. 

With some planning and setup, you can:

• Produce books for tiered customers. For example, Martin's department uses a single set of FrameMaker files to produce different documentation for their internal users, business partners, and customers. Each documentation set includes only the information required by each set of users. Not only can the content be different, but the information can be organized differently for each print or online output.
• Ensure consistent formatting. Setting up a single EDD or Style Sheet ensures consistent formatting. You can extend this consistent formatting across your documentation department, even if your department is in multiple locations.
• Ensure consistent organization. Setting up a single EDD ensures consistent organization by requiring a particular organizational structure. For example, if the EDD specifies that a procedure consists of an overview, an introductory phrase, and steps, the EDD lets you add only those elements to a procedure. This consistent organization can be extended across your documentation department, even if your department is in multiple locations, by having all writers use the same EDD.

Using structured elements to organize your content has many advantages. For example, you may choose to organize commands categorically in a manual that documents a programming language. The manual may provide considerable background information about each command, in addition to its syntax and arguments. The structured elements in your EDD let you automatically label the various types of content in the manual, in this case categories, commands, background information, syntax, and arguments.

Having the various types of content labeled this way makes it possible for VersiText to generate an online help system that excludes the background information and reorganizes the commands in alphabetical order. 

Martin uses FrameMaker version 7.0 and VersiText in this way to produce printed and on-line documentation for Encorp's generator power control systems. Martin also demonstrated how VersiText can be used as-is to produce HTML-based help and Microsoft HTML Help (compiled HTML help). Custom-engineered output modules (customized by Martin) are also available, allowing VersiText to be customized on a company-by-company or project-by-project basis.

Martin's FrameMaker/SGML/VersiText presentation was excellent, as is his bio: Martin indicated he followed this path to understand more about programming in order to make his job of communicating technical information easier. He also says a thirst for knowledge is healthy and that he constantly strives to learn more about areas related to technical communication. 

Obviously, Martin's search for knowledge has made him more marketable in this unpredictable market.

Martin has also worked as an independent technical writing consultant. In May 2001 Martin formed his own software company, GolehTek LLC. GolehTek's flagship product is VersiText.