Power Hour November 2010 Implementing Context-Sensitive Help Ben Allums Conference Number: 805-309-0248 Participant Code: 880-0006

December 2010 Power Hour Cancelled! Power Hour – November 2010 Agenda Survey Results Implementing Context-sensitive Help Webinars of Interest December 2010 Power Hour Cancelled! See you in January!

Power Hour – November 2010 Survey Results

Survey Results When to meet: January 27 2011

Survey Results Topics to cover: January 27 2011

Survey Results Topics to cover: Easy and efficient ways to generate HTML man pages via FM9 and WW2010 Webinar: Study Hall Effective strategy for use of external CSS - what NOT to use in Style Designer, exactly HOW WW outputs HTML in WebWorks Help & other HTML formats - so we know HOW to impl. CSS (Div and Span for example), a block by block analysis of Pages.asp, so we know intelligently how to alter, etc. Topic: Power CSS - Understanding ePublisher Page Templates and generated HTML

Survey Results Topics to cover: Implementing context-sensitive help (the 24th doesn't work, can you do a second one after the holiday?) Rescheduling to some other day (how about the 22nd for November and December) would be easier to schedule/commit to in light of holidays Recording: Power Hour Archive Conditional publishing with DITA Webinar: Show Me! on December 16th Customize the look of the Dynamic HTML style to have a 3 pane look like the WebWorks5 template only minus the Search tab/JavaScript portion Topic: Tri-pane HTML - Customizing Dynamic HTML 2010.3: WebWorks Reverb (see November Show Me! recording)

Implementing Context-sensitive Help Power Hour – November 2010 Implementing Context-sensitive Help

Implementing Context-sensitive Help Questions to answer What is context-sensitive help? How does one author for help? How do developers integrate help? What are the pitfalls to success?

Implementing Context-sensitive Help What is context-sensitive help?

What is context-sensitive help? Associating a specific program context to a specific content context

What is context-sensitive help? Requirements: Identify content Link application to content

What is context-sensitive help? Identify Context Topic Context Topic Context Topic Topic Context Topic Topic Topic

What is context-sensitive help? Identify Microsoft HTML Help reference.chm 3241 6324 concepts.chm 1324 tasks.chm 3456 #define topic_hlp 1324 #define topic_x 3241 #define topic_y 6324 2345 8767

What is context-sensitive help? Identify Eclipse Help com.help.ref idx idy com.help.cncpt idhlp com.hlp.task idask idrep idsug

What is context-sensitive help? Identify WebWorks Help reference x y concepts hlp tasks ask rep sug

What is context-sensitive help? Identify Context Topic

What is context-sensitive help? Link Content Application

What is context-sensitive help? Link Content authors Embedded topic identifiers External contexts Developers APIs URIs

What is context-sensitive help? Meet in the middle! Content Application Map + API/URI

Implementing Context-sensitive Help How does one author for help?

How does one author help? Content authors Embedded topic identifiers External contexts

How does one author help? Topics: Adobe FrameMaker TopicAlias marker Microsoft Word WebWorks TopicAlias marker (uses custom field codes) DITA <resourceid> Provides an identifier for applications that require them in a particular format, when the normal id attribute of the topic can't be used <resourceid id="fred" appname="sql0375"/>

How does one author help? Topics: DITA (non-standard) <othermeta> The <othermeta> element can be used to identify properties not otherwise included in <metadata> and assign name/content values to those properties <othermeta name="Topic" content="metric" /> ePublisher treats these like markers Set “TopicAlias” behavior

How does one author help? Contexts: Microsoft HTML Help Path to .chm C:\Program Files\Application\Help.chm

How does one author help? Contexts: Eclipse Help plugin.xml <?eclipse version="3.0"?> <plugin> <extension point="org.eclipse.help.toc"> <toc file="hierarchy.xml"/> </extension> </plugin>

How does one author help? Contexts: Base URI http://www.helpml.com:8088/help/index.jsp

How does one author help? Contexts (with ePublisher): ePublisher top-level groups Explicit contexts via Merge Settings dialog

Implementing Context-sensitive Help How do developers integrate help?

What is context-sensitive help? Link Developers APIs URIs

How do developers integrate help? APIs: Microsoft HTML Help #include "topics.h" HtmlHelp(hwnd, "hlp.chm", HH_DISPLAY_TOPIC, idh_topic)

How do developers integrate help? APIs: Eclipse Help WorkbenchHelp.setHelp(myDialogBoxn, org.eclipse.demo.doc.example.select_a_wizard_dialog);

How do developers integrate help? APIs: WebWorks Help (C/C++) #include "wwhelp/wwhapi.h" WWHelp_Startup(BaseHelpURL); ... WWHelp_DisplayHelp("beta", "section1"); ... WWHelp_Shutdown();

How do developers integrate help? APIs: WebWorks Help (JavaScript) var MyHelpset; help = new WWHAPI_Object("http://www.webworks.com/docs", "help_window"); ... help.WWHAPI_DisplayHelp("volume1", "myTopicAliasValue"); ... help.WWHAPI_CloseHelp();

How do developers integrate help? URIs: Browser based help http://www.helpml.com:8088/help/index.jsp?topic=/org.sample.help.doc/eclipse_csh/DHSC_BestPractices_eclipse_csh_plug-in.html

How do developers integrate help? URIs: WebWorks Help http://www.webworks.com/docs?context=volume1&topic=myTopicAliasValue

Implementing Context-sensitive Help What are the pitfalls to success?

What are the pitfalls to success? The Arena! Development Help Authors Content Application Map + API/URI

What are the pitfalls to success? Assuming too much responsibility Assuming too little responsibility Battling for supremacy! Not listening

What are the pitfalls to success? Assuming too much responsibility Development Help Authors Content Application Map + API/URI

What are the pitfalls to success? Assuming too little responsibility Development Help Authors Content Application Map + API/URI

What are the pitfalls to success? Battling for supremacy! Development Help Authors Content Application Map + API/URI

What are the pitfalls to success? Not listening Hearing suggestions as recommendations You say “I have a way to manage that in the documentation.” They hear “Tech Pubs is taking control away from Development!” Negative feedback Translates to “I haven’t thought about it!”

What are the pitfalls to success? Can’t we all just get along? Development Help Authors & Developers Help Authors Content Application Map + API/URI

What are the pitfalls to success? Meet in the middle! No single best way for every case Tech Pubs manages topic maps Development manages topic maps Joint committee with topic maps in spreadsheets Common XML format to inject into source and documentation Find one that works for your project

Implementing Context-sensitive Help Practice Authoring in FrameMaker, Word, DITA Configuring in ePublisher Delivering Let’s try it!

Power Hour – November 2010 Webinars of Interest

Webinars of Interest Show Me: December 16th at 11:30am Central Topic: Conditional Text – Maintaining Content for Multiple Audiences Learn what the ePublisher platform can do for you right out of the box. Hosted by members of the WebWorks staff Repeats on the 3rd Thursday of every month Sign-up at http://www.webworks.com/Resources/Events/Show_Me/

Webinars of Interest Study Hall: November 24th at 1:00pm Central Open forum for ePublisher users Ask questions or request help on custom projects Hosted by members of the WebWorks development staff Repeats on the 2nd and last Wednesdays of every month Join at http://www.webworks.com/Resources/Events/Study_Hall/

December 2010 Power Hour Cancelled! Webinars of Interest Archives: Power Hour http://www.webworks.com/Resources/Events/Power_Hour/Archive/ Show Me! http://www.webworks.com/Resources/Events/Show_Me/Archive/ December 2010 Power Hour Cancelled! See you in January!

Power Hour November 2010 Implementing Context-Sensitive Help Ben Allums