Context Sensitive Help_Remedy
- 1. Creating Context Sensitive Help Using Single Sourcing STC India, Chennai 6th Annual Conference December 2-4, 2004. Debjani Sen and Roger Dearth
- 2. 2 Session objectives • Define single sourcing • Analyze the need for single sourcing • Highlight the benefits and challenges of single sourcing • Provide guidelines for modularizing documents • Create context sensitive help at Remedy • Case study • Highlight how single sourcing is beneficial to the user • Conclusion
- 3. 3 Single sourcing defined “Single sourcing … creates multiple deliverables from one unmodified source document – that is, in the process of creating the deliverables, the source document is not edited or modified.” Sean Brierley “Single-sourcing allows you to reuse the same content in multiple documents and/or output formats.” Michele Marques “Single source materials are materials that come from a single location.” Ann Rockley, JoAnn Hackos “Single sourcing provides the facility to create, and store reusable content from a single source, and delivers that content to multi-channel information products for content users.” The Rockley Group
- 4. 4 Our definition of single sourcing • Writing content once and reusing it many times • Building modular information and assembling it into different formats (for example, print, web, and online help) • Designing information for different audiences
- 5. 5 Levels of single sourcing Level One Identical content, different output formats (for example, paper and online) Source Document PDF Help
- 6. 6 Levels of single sourcing (cont.) Level Two Static content customized for different information products (for example, user guide, online help, training materials) Elements of Source Document PDF Help
- 7. 7 Levels of single sourcing (cont.) Level Three • Content customized dynamically to meet different user needs • Information is stored in a database Content Database Custom Output
- 8. 8 Levels of single sourcing (cont.) Level Four Content customized dynamically to meet different user needs when they need it and updated automatically Database Custom OutputUsers
- 9. 9 Where are we at Remedy? • We are between level two and level three of single sourcing • We are re-thinking our documentation strategy • We plan to develop information as elements or chunks of information rather than assembling documents into books
- 10. 10 Single sourcing assumptions • Printed and online documentation must have overlapping content • If the content in your print and online documentation is significantly different, single sourcing may not be the right approach
- 11. 11 Need for single sourcing Analyze your audience • What are the users goals from the online help system? • What is the level of subject matter knowledge and experience that users have about the product? • Are they novice or experienced users of the product for which you are providing the online help system? • What kind of information are they looking for?
- 12. 12 Benefits of single sourcing • Reduces duplication of effort • Writers can update the source document once, reducing room for error when documents are updated • Improves consistency across various sets of documentation • Reduces review time • 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 • Saves time and money
- 13. 13 Challenges of single sourcing • High learning curve • The requirements for printed and online documentation might be very different to use a common source file • Requires 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 and tools
- 14. 14 Guidelines for modularizing documents Identify sections for print and help • Conditional text to differentiate between different output formats Examples: • Conceptual information and graphics will be for printed documentation only • Procedural information (that explains how to complete a task) will be included for both print and online • Pop-up topics or related information links for online only
- 15. 15 Guidelines for modularizing documents (cont.) • Chunk information by creating stand alone topics • Avoid references to sections that are dependent on positions, for example, references to “see below,” “the following section,” etc. • Avoid using sequential references • Include cross references to related topics
- 16. 16 Single sourcing at Remedy Goals • Provide PDF and context sensitive online help using the same source • Work with the constraints of limited resources and tight project schedules Implementation • Single source the FrameMaker content to context sensitive online help using WebWorks Publisher Professional
- 17. 17 Pre-work for context sensitive help • Make sure the FrameMaker document has been tagged correctly › Follow your style guide • Use a well established WebWorks template › We relied on our tools expert to build a WebWorks help template • Determine the level of context sensitivity • Determine the screens and tabs that require context sensitive help
- 18. 18 Pre-work for context sensitive help (cont.) • Work with the development team to integrate context sensitive online help into the application • Get commitment for time and resources from the development resources • Work with QA to develop a plan for testing the help
- 19. 19 Setting the stage Create markers in FrameMaker that point to screens or tabs that require context sensitive help • Define marker type called “Filename” in FrameMaker • Add markers to chapters and sections in your book that required a separate .htm page • Generate and save the book file
- 20. 20 Adding Filename markers Add filename markers to sections or chapters in your book file
- 21. 21 Generating single sourced context sensitive help • Generate context sensitive help using WebWorks • Test the help to make sure all the links work • Hand off the help to the development team so they can integrate it with the application • Test the help
- 22. 22 Results of single sourcing Source content in FrameMaker PDF Online Help
- 23. 23 Case study: Applying single sourcing to an OEM project Situation • Source documentation was created by an OEM vendor • Documentation included online help files that were also formatted as Microsoft Word documents for print • Online help created using RoboHELP Requirements • Required to deliver both context sensitive online help and a printed guide (PDF) to customers • Add new content to the existing information • Use FrameMaker to produce the printed guide • Easily update and maintain the content for both output formats
- 24. 24 Case study (cont.) Summary • Step 1: Estimate the documentation project • Step 2: Convert the online help files into source content • Step 3: Convert the context sensitive help tags • Step 4: Generate the context sensitive online help • Step 5: Test the help links • Step 6: Review the results of the conversion
- 25. 25 Step 1: Estimate the documentation project Approach: • Used single sourcing because the printed and online documentation included almost identical content Advantages of the single sourcing approach: • Works well in a deadline driven environment • Users get updated content that matches in print and online • One writer can maintain both online help content and the printed guide
- 26. 26 Step 2: Convert the online help files into source content • Converted the source HTML files (provided by the OEM vendor) to FrameMaker format • The conversion was done by our tools expert using a Perl script • HTML files were gathered into FrameMaker files • The original file names were retained as Filename markers in the FrameMaker documents
- 27. 27 Step 3: Convert the context sensitive help tags Source HTMLHelp files from RoboHELP FrameMaker MML filesUsing a Perl script Single source authoring of files in FrameMaker (FM) Using a FrameScript Translate HTML tags to FrameMaker MML markup Pull MML files into FrameMaker files
- 28. 28 Step 3: Convert the context sensitive help tags (cont.) Name of HTML file in RoboHELP File conversion Custom filename marker in FrameMaker Filename marker in RoboHELP Filename marker in FrameMaker hlp_about.htm hlp_about (.htm is added by WebWorks) hlp_configuring_clients.htmhlp_configuring_clients hlp_license.htm hlp_license hlp_sdquery.htm hlp_sdquery
- 29. 29 Step 4: Generate the context sensitive online help • WebWorks was used to generate the help files from the FrameMaker source files • The context sensitive links in the online help system were preserved WebWorks Publisher Create help files with context sensitive help tags based on Filename markers WinHelp context sensitive help
- 30. 30 Step 5: Test the help links Tested the context sensitive online help after it was integrated into the application
- 31. 31 Step 6: Review the results of the conversion Conversion results hlp_configuring_clients.htm sample context sensitive help topic
- 32. 32 What does all this mean • Evaluate whether single sourcing is the right approach for you • If you choose to single source, decide on your approach to create single sourced context sensitive help
- 33. 33 Conclusion • Single sourcing efforts are slowly moving to the direction of database publishing • Information is stored in a database and writers query to extract specific information
- 34. 34 References • Ament, Kurt. Single Sourcing:Building Modular Documentation. Noyes Data Corporation/Noyes Publications; December 1, 2002 http://infotektur.com/projects/singlesourcing/index.html • An Introduction to Single-Sourcing. http://www.simplywritten.com/library.htm • Finger, Hedley. The Joy of Single Sourcing. http://www.soltys.ca/techcomm/articles/the_joy_of_single- sourcing.html • Hackos, JoAnn. The Impact of Single Sourcing and Technology. http://www.rockley.com/articles/Single_Sourcing_and_Technology.pdf
- 35. 35 References (cont.) • Hackos, JoAnn. Single-Source Content Management If, Why, and How. http://www.comtech-serv.com/pdfs/hackos.pdf • Rockley, Ann. Managing Enterprise Content: A Unified Content Strategy. New Riders, October 17, 2002 • The IdeaStore. Single-Sourcing and Content Reuse with FrameMaker and FrameMaker +SGML. http://www.theideastore.com/single- sourcing.content-reuse.html • The Rockley Group, Enterprise Content Management through Single Sourcing. http://www.rockley.com/articles/Rockley.FN.ATI_Webinar_Presentatio n_6.18.02.pdf
- 36. 36 Tools Adobe FrameMaker • The latest version of FrameMaker is 7.1. We are using FrameMaker 6.0. http://www.adobe.com/products/framemaker/main.html FrameScript • FrameScript is an add-on to FrameMaker that lets you write scripts to automate most parts of FrameMaker. http://www.FrameScript.com or http://www.fml.com IXGen • IXGen is an indexing and marker management productivity tool for FrameMaker. http://www.fsatools.com
- 37. 37 Tools (cont.) Perl • Perl is an open source, cross platform programming language. http://www.perl.org MML • MML stands for “Maker Markup Language.” It allows you to mark up a text file with a few simple tags, which FrameMaker then converts to a proper FrameMaker binary document. It is particularly well suited for generating documents programatically. You wouldn’t want to generate a MIF file by hand, but MML is designed to be created by humans or programs. • MML is documented in the FrameMaker online documents in Program FilesAdobeFrameMaker <version>OnlineManualsMML_Reference.pdf.
- 38. 38 Contact Us Debjani Sen debjani.sen@remedy.com Roger Dearth roger.dearth@remedy.com