context sensitive help_remedy
TRANSCRIPT
Creating Context Sensitive Help Using Single Sourcing
STC India, Chennai6th Annual ConferenceDecember 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 OneIdentical content, different output formats (for example, paper and online)
Source Document
Help
6
Levels of single sourcing (cont.)
Level TwoStatic content customized for different information products (for example, user guide, online help, training materials)Elements of Source
DocumentPDF
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 FourContent customized dynamically to meet different user needs when they need it and updated automatically
Database Custom OutputUsers
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
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 contentAdvantages 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
FrameMakerMML files
Using a Perl script
Single sourceauthoring of files
in FrameMaker (FM)
Using aFrameScript
Translate HTML tags to FrameMaker MML markup
Pull MML filesinto FrameMakerfiles
28
Step 3: Convert the context sensitive help tags (cont.)
Name of HTML filein RoboHELP
File conversion Custom filenamemarker
in FrameMaker
Filename marker in RoboHELP Filename marker in FrameMaker
hlp_about.htm hlp_about (.htm is added by WebWorks)hlp_configuring_clients.htm hlp_configuring_clientshlp_license.htm hlp_licensehlp_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
WebWorksPublisher Create help files with context
sensitive help tags based on Filename markers
WinHelp contextsensitive help
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 resultshlp_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, 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
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_Presentation_6.18.02.pdf
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
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 Files\Adobe\FrameMaker <version>\OnlineManuals\MML_Reference.pdf.
Thank You
Questions?