1. Creating Context Sensitive Help Using Single Sourcing
STC India, Chennai 6th Annual Conference December 2-4, 2004.
Debjani Sen and Roger Dearth

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. 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. 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. Levels of single sourcing
Level One
Identical content, different output formats (for example, paper and online)
Source Document
PDF
Help

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. 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. Levels of single sourcing (cont.)
Level Four
Content customized dynamically to meet different user needs when they need it and updated automatically
Database
Users
Custom Output

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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. Adding Filename markers
Add filename markers to sections or chapters in your book file

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. Results of single sourcing
Source content in FrameMaker
PDF
Online Help

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. 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. 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. 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. Step 3: Convert the context sensitive help tags
Source HTMLHelp
files from RoboHELP
FrameMaker MML files
Translate HTML tags to FrameMaker MML markup
Using a Perl script
Pull MML files into FrameMaker files
Using a FrameScript
Single source authoring of files in FrameMaker (FM)

28. Step 3: Convert the context sensitive help tags (cont.)
Name of HTML file in RoboHELP
Custom filename marker in FrameMaker
File conversion
Filename marker in RoboHELP Filename marker in FrameMaker
hlp_about.htm hlp_about (.htm is added by WebWorks)
hlp_configuring_clients.htm hlp_configuring_clients
hlp_license.htm hlp_license
hlp_sdquery.htm hlp_sdquery

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
WinHelp context sensitive help
Create help files with context sensitive help tags based on Filename markers

30. Step 5: Test the help links
Tested the context sensitive online help after it was integrated into the application

31. Step 6: Review the results of the conversion
Conversion results
hlp_configuring_clients.htm sample context sensitive help topic

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. 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. References
Ament, Kurt. Single Sourcing:Building Modular Documentation. Noyes Data Corporation/Noyes Publications; December 1,
An Introduction to Single-Sourcing.
Finger, Hedley. The Joy of Single Sourcing. sourcing.html
Hackos, JoAnn. The Impact of Single Sourcing and Technology.

35. References (cont.)
Hackos, JoAnn. Single-Source Content Management If, Why, and How.
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. sourcing.content-reuse.html
The Rockley Group, Enterprise Content Management through Single Sourcing. _ pdf

36. Tools Adobe FrameMaker
The latest version of FrameMaker is 7.1. We are using FrameMaker
FrameScript
FrameScript is an add-on to FrameMaker that lets you write scripts to automate most parts of FrameMaker. or
IXGen
IXGen is an indexing and marker management productivity tool for FrameMaker.

37. Tools (cont.)
Perl
Perl is an open source, cross platform programming language.
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 Files\Adobe\FrameMaker <version>\OnlineManuals\MML_Reference.pdf.

38. Contact Us Debjani Sen debjani.sen@remedy.com Roger Dearth

39. Thank You
Questions?