Single Source Documentation with Reference to Adobe Framemaker and Webworks Publisher

Single Source Documentation With reference to Adobe FrameMaker and WebWorks Publisher

Raj Ekanatheeswaran Suchitra Govindarajan

echnical writing does not merely Is there any way to produce media relate to writing documents. The neutral contents that will help you Tchallenge lies in how you deliver focus more on developing contents these documents. With rapid changes than the final deliverable? Yes! single in technology and business conditions, sourcing can address these issues. customers have begun redefining their requirements not only in terms of With single sourcing, you can write what they want, but also how they information once, and reuse it many want it. This applies to documentation times for multiple media and audi- as well. ences. A typical single source document contains both medium-neutral In the seventies and eighties, docu- and medium-specific content, and is mentation explicitly referred to print designed to take advantage of the “What is media. With the advent of the digital strengths of different media. This Single Sourcing?” age, the need to access information paper focuses on single sourcing as a anywhere and anytime became essen- strategy with reference to Adobe The process of using tial. It is then that people started FrameMaker and WebWorks Publisher a single “source” realising the need for online documen- as tools. document to produce tation that can be shipped with any different output product or downloaded from the formats including Internet. Currently documentation print, Web(XML/ mostly relates to the online media. Contents HTML), and online What is single sourcing help (WinHelp, Let us look at this situation: How will JavaHelp, and so on.) you produce the same content for Benefits in single sourcing three different media say, print, PDF, Challenges in single sourcing and online HTML help. The only option What tools to use that was available until early nineties is to use the conventional documenta- Getting started tion method where you use different How single sourcing works approaches for various media. But how Using WebWorks do you ensure that the content syn- chronizes across multiple media? How do you save your efforts involved in documenting for multiple media? “What is single sourcing?” “What are the challenges in single sourcing?” ingle sourcing is the process of Susing a single “source” document to produce ike any other approach, single sourcing presents different output formats including print, Web (XML/ La few challenges that you need to seriously HTML), and online help (WinHelp, JavaHelp, and so consider to evaluate whether this model will cater to on). In single sourcing you write information once your documentation requirements. These are just and reuse it many times to cater to multiple audi- challenges and not limitations: ences and media. • The requirements for print and online documentation are different The single source document: • It requires extensive ground work in terms • Understands and takes advantage of the of modularizing and organizing your source strengths of different media documentation • Contains both medium-specific and medium- • The initial learning curve is very steep. neutral content You need dedicated resources to set up the single source model Single sourcing is not just converting a document • It is challenging to get the “buy in” from from one format to another. everyone within the organization

“Why should you single source?” You use single sourcing here are many convincing reasons to adopt when print and online help Tsingle sourcing as your documentation model. contents overlap! This list summarizes the most signicant ones: • You need not duplicate your efforts to produce different documents for print and “What is Adobe FrameMaker?” online media. • You can just update the source document dobe FrameMaker is an integrated document and apply changes globally across all Apublishing application with these features: deliverable formats. As a result, you can • Page Layout ensure consistency across various sets of • Word Processing documentation. • Graphics • You need not maintain multiple documenta- • Math Equations tion sets. • Long Document Handling • You can deliver products to the market • File Compatibility Across Major Platforms faster than ever before. You do not put in • Conditional Text extra time and effort in producing the • Hypertext document. Adobe FrameMaker: Can create BOOKS from multiple DOCUMENTS which have PAGES that contain OBJECTS which may hold TEXT

Adobe FrameMaker Each FrameMaker document also includes FORMATS & to provide a consistent look and layout. Quadralay WebWorks Publisher FrameMaker documents include CONDITIONAL TEXT, is the industry-standard which are elements in a Frame document that you single sourcing tool kit! can use to display or hide text or images. Adobe FrameMaker Model and Components

“What is WebWorks Publisher?” For example: - Conceptual information will be for print WebWorks Publisher is a single sourcing tool that only adds on FrameMaker's publishing capabilities. It is - Procedural information (that explains how not a Help Authoring Tool and works only in con- to complete a task) will be for print junction with FrameMaker (A different version exists and online for Word). It can produce Online Help, HTML based help, XML based help, and Sun JavaHelp. • Create a compact list of paragraph and character tags in FrameMaker WebWorks, like FrameMaker, is a template driven tool. It relies on a set of predefined templates to - Create tag names that make sense and automate the conversion process. It integrates well can be easily mapped with FrameMaker and understands all the components of a FrameMaker document, from paragraph styles “How do you get started?” to conditional text. After you decide that single sourcing is your documentation model, you must set up a WebWorks “How do you prepare for single compatible FrameMaker template that can have sourcing?” tagged content. You then shift your focus to WebWorks to work on the conversion process. hile planning for your single sourcing documen tation model, you must consider these key W This is what you do: points: • You create a WebWorks Publisher project to • Modularize your FrameMaker document: convert a set of FrameMaker books to - Chunk information by creating stand your chosen output format. alone topics • Each WebWorks Publisher template includes a - Avoid references to sections that are set of pre-defined styles you can use to dependent on positions, such as “see control the appearance of your output. below”, “the following section”, • You can map each FrameMaker tag with a and so on style defined in WebWorks Publisher. - Create references that provide the • WebWorks Publisher takes care of the details topic name of producing the code for you, whether it is - Plan for audiences who do not always HTML, XML, or one of the specialized online look for information sequentially Help formats

• Create conditional text if necessary to specify which output should be mapped to “WebWorks Publisher is a single source online help and print. documentation tool that lets you convert FrameMaker books to various help formats” “How do you use WebWorks for “How do you do the conversion?” single sourcing?” After you set up your WebWorks compatible WebWorks is a versatile software that provides a lot FrameMaker books, you can use WebWorks to create of customization capabilities. The first time you use a project to convert these books into online help. WebWorks, you must select one of the pre-defined You can use any of the pre-defined WebWorks templates, based on how you want to deliver your templates or design your custom template to do the content. conversion.

Once you complete a default WebWorks project, you You will use the following conversion process to can compare the output with your FrameMaker convert a FrameMaker book to Online HTML Help: document and perform the customization of your 1. Start WebWorks Publisher and create a new choice. Customization involves working primarily project using a pre-defined or custom with: template. • Style Mappings that decide how your FrameMaker tags convert to WebWorks formats. • Style Designer that lets you create new styles or edit existing ones.

Each WebWorks template comes with a default set of paragraph and character styles that you can use as the base for creating new ones. Apart from the changes to styles, it is also easy to add your company logo, a custom header or footer or custom navigation icons. The specific procedures for these changes depend on the specific template you are using, and may require basic knowledge of HTML, CSS and XML.

2. Specify a project name and location where “WebWorks Templates” you want to store this project. WebWorks Publisher ships with these 3. Specify a FrameMaker book to convert. pre-defined templates: 4. Specify the FrameMaker-->WebWorks Publisher mappings. Online Help Templates • WebWorks Help 3.0 • Microsoft HTML Help • Microsoft WinHelp HTML Templates • Dynamic HTML • Accessible HTML • Simple HTML XML Templates • XML + CSS • XML + XSL Sun JavaHelp Template 5. Specify conditions, if any for your output. 6. Specify online help formats for FrameMaker “How do you create a custom cross-references. WebWorks template?”

This is how you do: 1. Open WebWorks Publisher and create a new default project: a. Start a new project. b. Define project propertes. c. Generate online help.

2. Refine project properties: a. View the output and determine the changes you want to make. b. Refine styles - Edit default styles or 7. Finish generating your project. create new styles. 8. Open the generated HTML index file to view c. Change style mappings. the output. 3. Regenerate online help. 4. Save the project as template.

Single Sourcing in a Nutshell Selectica, Inc. (Nasdaq:SLTC) is a leading provider of Interactive Selling Systems (ISS) that transform the way compa- nies sell, service, and compete. Selectica’s ISS platform provides robust capabilities to enable industry-specific guided selling applications that streamline and accelerate the process of configuring, pricing, and purchasing complex products and services. Businesses that deploy ISS are able to empower business managers to quickly and easily modify product, service, and price information enterprise-wide to ensure proper margins and to stay ahead of changing market conditions. Across a wide range of industries, Selectica’s ISS has demonstrated an ability to increase productiv- ity, improve order accuracy, boost return on investment and establish and maintain a competitive advantage.

Selectica Headquarters: Selectica India Development Centers: 3 West Plumeria Drive Chennai Pune San Jose, CA 95134-2111 23, Anna Salai Sharada Arcade Chinnamalai 685, Pune-Satara Road www.selectica.com Saidapet Bibwewadi Chennai - 600 015 Pune - 411 037 Tel: 2 220 2100 Tel: 421 1906