Embedded help at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

This is Dave Gash‘s second session at the conference! It’s called “Embedded help: nuts and bolts”. The aim was to show us how to do embedded help, rather than why embedded help is a good thing. Dave said there’ve been plenty of presentations in years gone by, explaining when embedded help is required and what it looks like.

The goals is to show us two ways to add embedded help to your web app:

• Put the snippets into an HTML help page
• Put the snippets into an XML file

Dave explained that his code samples are plain old JavaScript rather than using a library like jQuery, because it’s more accessible to everyone and because it will work locally.

First method: Adding embedded help via HTML

For the purposes of this demo, Dave has created a “phony” web app: GalaxyDVR (HTML). Notes:

• Look at the embedded help panel at the bottom.
• remember Dave’s warning that the aim is to show us how to create embedded help, not how to make it beautiful.
• See how the content of the bottom panel changes when you click on different parts of the screen.
• Click the link in the panel to see the full help system.
• Note how the first sentences in each section of the full help system correspond to what appears in the panel on the app.

Dave said that this is the more difficult than using DITA, but still very feasible. It works by using a CSS class of “shortdesc”. The web app reads the entire content page and looks for the paragraph that has the class of “shortdesc” and sticks it into the <div> that defines the help panel.

How to prepare the content: Create it with any tool that allows you to define a specific reachable HTML element. It doesn’t have to be a CSS style. It could be a <span> with an id, for example. You could even style it so that it doesn’t appear in the full help system.

Dave was using DITA for content storage, which was then transformed to HTML that contained the necessary identifiers. But he emphasised that you don’t need to use DITA. You can have straight HTML instead.

The help files must be accessible to the web app.

How to retrieve the help content when the user clicks the relevant area of the page: A JavaScript function reads the entire HTML file as a string, finds the content identified as embedded help, extracts it to another string, and embeds it into the panel.

Now Dave walked us through the code that does the work. I haven’t tried to capture this in the notes. Some extra bits to note: The page loads some default help content via the HTML body’s onload event. Another piece of code tacked on the standard string that says “For more information, see the full help system“. And remember to add CSS to style the embedded help content.

Second method: Adding embedded help via XML

See the demo app: GalaxyDVR (XML). This one is based on XML. Note also that there’s a specific piece of embedded help for each control on the page, rather than for just the sections. There’s also help for each element of a dropdown.

Dave says this version is much simpler. You don’t need a web help system. Create the embedded help all in one file. You can use any XML text editor. The XML can be of a format of your own choice. The input and output is just a file. There’s no build or conversion process required.

Every embedded help snippet has an id, which is a unique identifier. You can use any naming convention you like. For example:

<eh id="fc_avail">My help text</eh>

<eh id="pc_pin">More help text</eh>

When the user selects a control, the JavaScript looks in the XML file, locates a specific piece of text that matches the control, and returns the help text into the box on the screen. How does it identify the relevant text? The element that the user clicks has an id that matches the id of the help text element. The XML file is read into an XML document object (rather than as a string). Then you identify the help text, extract it, and embed it into the help panel.

Note: Instead of using the onclick event to trap the user’s action, you’ll need to use onblur. Otherwise you’re overriding the core app functionality by usurping the onclick event. Also, people may want help before they actually click the button. Using onfocus will work when users tab through the fields too.

Comparing the two methods

Dave emphasised that neither method is better. Think about what you want to do:

• The HTML method creates the entire web help system including the embedded help content. That’s single sourcing. Also, the HTML method less granular, and distributes the embedded help content amongst the other content. You need an entire separate help system, including some kind of build system to create the web help system.
• The XML method is not single sourced. You may end up with a set of embedded help content and a separate set of web help content. But this may not really hurt you. You just need to ensure you maintain both. The XML method is more granular, and it keeps all the embedded help content together. You’re not required to have an entire web help system.

Dave also noted that his implementation is just an example. Take his code and change it to suit your requirements. The goals of Dave’s presentation are to show what’s possible and help us feel we can do it.

Conclusion

This was an excellent walkthrough of a couple of embedded help solutions. Thanks Dave for a couple of great demos!