Context is King - Four Royal Tips on Providing Context-Sensitive Help in Confluence

9 min read /

A king would never walk to the library if he wanted to consult a book. Rather than climbing down from his throne, he’d tell one of his servants to find the desired volume and bring it to him, wherever it may be.

Today, all users are treated like royalty in the sense that they have instant access to information of all kinds. Context-sensitive help does the job of the king’s servants – providing the required knowledge directly and conveniently, and sparing users the bother of interrupting their work to browse through the entire help library.

Imagine that a user needs advice on which option in a dialog window to choose. Clicking the help button or pressing the F1 key pulls up the relevant help topic right away. To be truly useful, help content must be provided at the right time and in the right form. And when it comes to creating and distributing help resources, what could be better than Confluence, the collaborative, web-based knowledge platform?

Here are four tips for providing context-sensitive online help fit for a king.

Make Your Help Content Available Online

In most cases, the best way to provide users and contributors with access to your documentation is to make it available on a public Confluence space. Readers can browse through support pages, use the Confluence full-text search, add a comment to provide feedback, or export content to PDF or other offline formats.

Here's how to make a Confluence space available to your users:

  • Allow a specific Confluence user group to access your documentation space, or even enable anonymous users to view your wiki-based help site.
  • Customize the space's theme to reflect corporate design guidelines. Or go one step further and give your content a whole new look & feel – using our Scroll Viewport add-on.
  • If you're struggling with multiple spaces for individual product variants or versions, you could manage those documentation spaces using our Scroll Versions add-on.
  • And if online access to your Confluence platform is not an option – for instance, if your help content needs to be integrated with an existing portal, or if Confluence runs behind a firewall – you can take a different route: export your content.

Options for exporting your Confluence space as static web content:

Add Deep Links to Your Online Help

You tie in online help by incorporating links to corresponding help pages in your product's user interface. Users simply click to receive instant assistance. To give you an example, we at K15t Software provide documentation links to the relevant help page on the configuration pages of our Scroll Exporters:

When you use a Scroll Exporter to create static webpages, you'll notice that the Confluence page titles are used as file names by default. For example, Scroll HTML Exporter will export a page with the title "Getting Started" to a file named "getting_started.html". The link to a help page will then look like this:

http://helpcenter.yourdomain.com/docs/getting_started.html.

Advice on File Naming
If you wish to change this default behavior, you can modify the export settings for file name, whitespace and handling special characters, and for the file extension (.xhtml or .html).

It's essential to make all your online help files permanently available through the use of stable addresses (URLs). Nothing is more frustrating to readers than stumbling on broken links and being shown an error message instead of the help they wanted.

When exporting your Confluence content, e.g. with Scroll HTML Exporter, you may notice that by default, the file name changes if a Confluence page's title has been changed. To avoid having to check and fix referral links to your online help every time you export your Confluence content, choose one of the following options:

  • Export using the file naming option Page ID only (see screenshot below), which will generate files with names like 123456.html. This approach is not ideal for search-engine optimization.
  • Alternatively, use Scroll Versions to define unique keys that always stay the same for each of your help content pages, such as http://help.yourhost.com/docs/getting_started.html.  

Let's take a closer look at the second option, which uses Scroll Versions. This add-on’s page key functionality is extremely useful in scenarios where a Confluence space is made available to the public. But it's also handy when exporting your Confluence content through a Scroll Exporter add-on.

Using Page Keys for Publicly Accessible Confluence Spaces

A page key in Scroll Versions works like a nickname. Each Confluence page can be assigned its own unique key. Once bestowed, that page’s nickname sticks forever.

You create an alternative URL for accessing a page by setting a page key. This "nickname URL" contains the unique page key plus the space key, according to the following pattern <Base URL>/display/_PK/<Space Key>/<Page Key>. 

This URL will stay the same even if the page title changes and regardless of which version of the page's content is currently published.

Example
 Users can access the context-sensitive help page mentioned earlier both from the product's user interface also via https://www.k15t.com/display/_PK/CHM/connection-config.

Page Keys and Scroll Exporters

If you've decided to export your Confluence content to HTML, CHM, or EclipseHelp using a Scroll Exporter, you can still benefit greatly from Scroll Version's Page Key feature:

  1. Assign a page key to each Confluence page that requires a permanent link for context-sensitive help.
  2. In your Scroll Exporter's export settings, choose this file naming option: Scroll PageKey, fallback to Page ID.

Files included in your export will then be assigned names like MyPageKey.html. And those file names will endure, no matter whether the page name or hierarchy changes.

Embedding Help Content into Desktop Apps

Finally, let's take yet another step forward. If you are among our readers who build and ship Windows applications as a product: you should really consider embedding your context-sensitive help content in your Windows application itself. That way, your users will benefit from the best possible "F1 help" experience. It’s very easy to make this happen – with the Scroll CHM Exporter add-on for Confluence.

The CHM (Compiled HTML Help ) file format is and remains the gold standard for providing context-sensitive help for Windows apps that is available offline.

Using Scroll Versions and its Page Key feature, you can include links to help pages in the CHM file and the corresponding Windows application screens.

Building embedded, context-sensitive CHM help

  1. Ask your Windows application developer to provide context help IDs for the relevant user interfaces. 
  2. Make sure those context IDs are comprised only of integer numbers (as required by the CHM format).
  3. Add each integer context ID as a Page Key to the corresponding Confluence page.
  4. Start exporting your Confluence content to the CHM format using Scroll CHM Exporter.

After performing these steps, you'll have an embedded help application that provides full-text searching, index terms, and a built-in table of contents.

What's Next?

To keep your help contents up-to-date, just re-export your Confluence content. You can even automate this step by bundling the exported CHM artifact with the next build of your software.

Whichever way you choose to provide context-sensitive help, your users will enjoy easy access to your documentation. After all, the customer is king – and no doubt expects right royal treatment. 

Turn your Confluence-based documentation into a context-sensitive help tool, and try the Scroll content management add-ons for Confluence with a free 30-day trial.

If you have any questions, drop us an email at info@k15t.com.