Implementing Single Sourcing for Online Help Debjani Sen Information Developer Peregrine Systems STC Region 8 Conference, Nov 1-3, 2001

Session Objectives Define single sourcing Highlight the benefits of single sourcing Discuss the challenges of single sourcing Paradigm shift in online help creation Evaluate some available single sourcing tools Provide guidelines for modularizing new documents Highlight how single sourcing is a valuable investment for the writer and the company Case Study

What is Single Sourcing? Writing information once and reusing it many times Converting the source document to produce different output formats including print, training information (tutorials), web (HTML, XML), online help (WinHelp, JavaHelp,etc) Designing information for different audiences

Single Sourcing Workflow

Single Sourcing Assumptions The content in your printed and online documentation has to have overlapping information for single sourcing to be successful If the content in your printed and online documentation is significantly different, single sourcing may not be the right approach

Benefits of Single Sourcing Saves time and money Reduces duplication of effort Writers can update the source document once, reducing room for error when documents are updated –You do not have to maintain multiple documentation sets Improves consistency across various sets of documentation and users get documents that are: –up to date with the latest changes –accurate –effective Reduces review time

Benefits of Single Sourcing (cont.) Reduces translation costs by limiting the total volume of text created and reusing the same document source for different outputs Allows you to bring products to market more quickly than before

Challenges of Single Sourcing High learning curve The requirements for printed and online documentation are too different to use a common source file Requires tremendous up front work in terms of modularizing and organizing your source documentation Developing templates require time and dedicated resources Challenging task to get “buy in” from everyone within the organization Requires getting used to new technology Initial efforts may not always be successful

Paradigm Shift in Online Help Creation Creating Online Help the Current Way –Create source document using Word or FrameMaker –Copy and paste relevant information from the source document into an online help creation tool like RoboHELP –Manually format the source information –Repeat this process for version changes Creating Online Help the Single Sourced Way –Create modular source documents in FrameMaker –Use the pre-defined templates in the single source tool to automatically convert and map your source information into an online help format –Customize templates if required –Save and reuse your templates for new versions

Guidelines to Convert Existing Documents to Online Help Modularize your FrameMaker documentation –Chunk information by creating stand alone topics –Avoid references to sections that are dependent on positions, for instance, references to “see below”, “the following section”, etc –Create references that provide the topic name –Cater to readers who do not always look for information sequentially

Guidelines to Convert Existing Documents to Online Help (cont.) Create conditional text if necessary to specify which output should be mapped to online help and print –Conceptual information will be for print only –Procedural information (that explains how to complete a task) will be for print and online Create a compact list of paragraph and character tags in FrameMaker –Create tag names that make sense and can be easily mapped

Available Tools for Single Sourcing WebWorks Publisher Professional Edition 7.0 by Quadralay Corporation –15 day trial version –Upgrade from Standard Edition costs $850 –New version costs $1195 ForeHelp Pro 5.0 by ForeFront Incorporated –$349 per license Mif2go by Omni Systems –No trial version –$295 per license AuthorIT V3 Enterprise Edition Fixed License by AuthorIT Software Corporation –Based in Auckland, New Zealand –$699 per license

WebWorks Vs. ForeHelp WebWorks Publisher 7.0 –Allows you to create the following types of help: Accessible HTML Dynamic HTML Microsoft HTML Help Microsoft WinHelp Simple HTML Sun JavaHelp WebWorks Help 3.0 XML + CSS XML + XSL ForeHelp Pro 5.0 –Allows you to create the following types of help: ForHelp WinHelp InterHelp HTMLHelp JavaHelp

WebWorks Vs. ForeHelp (cont.) WebWorks Publisher 7.0 –Runs on the following platforms: Windows 95, 98, NT, ME, 2000 SPARC Solaris 2.5 and later HP/UX 10.2 and later AIX 4.1.x and later –Convert the content directly from a FrameMaker book file –Convert the contents of the entire book file at once –Create, save, and reuse your own template –Automatic mapping of styles –Overwrite existing project names –Manually run a compiler to generate a compiled help file ForeHelp –Runs on the following platforms: Windows 95, 98, 2000, NT –Save the Frame book as a mif (maker interchange format) file before converting to a generated help file –Convert each chapter individually –Manual mapping of each style that you want to convert to the online format –Cannot overwrite existing projects –Automatically generates a compiled help file

Key Differentiator Conversion with WebWorksAuthoring with RoboHELP

Case Study: Online Help Project within the CRM Division, Mountain View, CA Convert a sample manual to HTML Help View the results of the conversion Customize the WebWorks template to create our company specific template

The Conversion Process 1.Create a project by selecting a pre-defined template 2.Specify a project name 3.Specify the FrameMaker file or book to convert 4.Specify mappings

The Conversion Process (cont.) 5.Specify any conditions to include in your output 6.Specify how to convert your cross references 7.Finish generating your project

Compiling the Help File Compile the.hhp file that has been generated Open the generated.chm file to view the contents of your output

Results of the Conversion: Help Generated with WebWorks

Style Sheet for the WebWorks Generated File

Help Generated with RoboHELP

Style Sheet for the RoboHELP Generated Help File

Customizing the WebWorks Template WebWorks Publisher comes with a set of pre- defined templates that you can modify Map your Frame paragraph and character styles to the WebWorks styles –Unmap tags that have been manually mapped to the default WebWorks styles and map them to a more appropriate style –Delete mappings that are not used –Break up your FrameMaker topics to individual HTML pages

Customizing the WebWorks Template (cont.) Map your conditional text Map your cross reference formats to online replacement formats Modify the style sheet (.css file) to control the appearance of your generated output

Working with the WebWorks Style Sheet WebWorks generates two style sheets: –document.css that contains the settings for your project –catalog.css that contains style definitions for paragraphs, characters, and tables Define your style, layout, and formatting specifications in the Style Designer, which is populated in the.css file Generate the output to view the results of your new style

Using Your Own Style Sheet Create your own style sheet Replace the WebWorks generated style sheet with your own by adding it to the Support directory where the document.css file is stored Regenerate the output to read your style sheet

Saving the Project as a Template Save the project as a template using the Save As Template feature in WebWorks WebWorks stores the template in the WebWorks Publisher directory You can reuse the template for other projects

Single Sourcing in a Nutshell

Future of Single Sourcing New concept that will take time to get used to The potential of WebWorks seems promising as future versions of the application are released with a more intuitive graphical user interface than before Single sourcing efforts are slowly moving to the direction of database publishing where information is stored in a database and writers query to extract specific information

Conclusion Evaluate whether single sourcing is the right approach for you and your company If you choose to single source, decide on the appropriate method and conversion tool that will make publishing easy and cost effective for your business needs

References Altom, Tim. Single-Source and the Bottom Line. Retrieved August 19, 2001, from the World Wide Web: Hackos, JoAnn and Rockley, Ann. Single Sourcing. Retrieved July 28, 2001 from the World Wide Web: Snavely, Deborah. Single Sourcing from FrameMaker to Forehelp Premier Retrieved August 3, 2001, from the World Wide Web: The Rockley Group, Enterprise Content Management through Single Sourcing. Retrieved July 28, 2001 from the World Wide Web: The IdeaStore. Single-Sourcing and Content Reuse with FrameMaker and FrameMaker +SGML. Retrieved August 2, 2001, from the World Wide Web:

Contact Information Debjani Sen Peregrine Systems Mountain View, CA