Theresa explains,

The traditional way of providing content in a context-sensitive help link has been to link to the procedure for the page. Not only can this be limiting for the user, but it also can be limiting for the writer and the company. By picking a specific procedure, the writer is guessing at what the user wants to do on the page. While usability testing would give us more insight, if we don’t have this option, we can make the context sensitive help link more applicable to more people by providing a link to both a How topic and the Why, When, and Who information.

If we don’t provide additional options in the context-sensitive help, we are, in effect, making it more difficult for users to have their questions answered. By forcing them to browse and search through a help system they may be unfamiliar with, and by not highlighting the various options available for that screen, window, or page, we limit the options for the user and perhaps contribute to higher support costs.

To provide a variety of links to the user, you can manually list them, which is tedious and prone to error. Or you can use something like Related Links or  Concept Links, which shows a list of links in a hard-to-see pop-up. However, there’s also another option: relationship tables. I’m new to this concept, but my initial experience with them has gotten me excited.

Relationship tables come from the world of DITA, but Madcap now gives you the ability to create them in Flare 5. From one table you can manage all the related links for your entire project. Although you can define exclusions and inclusions, basically links in the same row are part of a family, and that family can appear on each topic that you embed the relationship table on.

For example, in the following table, I have four columns.

After inserting a relationship table proxy into your Flare masterpage, and setting each link type as a “Family” link type, here’s what automatically shows up on each page.

On all the plugins pages, you’ll see the following:

Related Concepts

• About Plugins

Related Tasks

• Installing Plugins
• Editing Plugins
• Removing Plugins

Reference Reference

• Lists of Recommended Plugins

Note: If you’re viewing the Installing Plugins page, the Installing Plugins doesn’t appear in the list of links. (The same smart exclusion isn’t true of Flare’s Concept links.)

On the themes pages, the list of related links would look like this:

Related Concepts

• About Themes
• Theme Hierarchy
• Columns in Themes

Related Tasks

• Installing Themes
• Modifying Theme Stylesheets
• Customizing Theme Categories

Reference Topics

• Best Magazine Themes

The cool thing is that you can manage all your related links from this one table. You can also specify more details with relationship tables, such as having links only appear on certain pages and targets, and applying conditional tags. But the basic concept is simple.

I’ve even styled my relationship table links so that they float in a narrow side column to the right of the main topic. My approach for context-sensitive help is to list the most common task for the page in the main column, and then provide the list of related links in a sidebar on the right. If the user clicks the help and says, no, that’s not what I want, he or she won’t need to scroll down to the end to see related topics.

For more information on relationship tables in Flare, see About Relationship Tables in Flare’s help.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

1. Make your help a mile wide and thirty seconds deep.

Users spend about 30 seconds on a help topic, so keep it short and get right to the point. On the other hand, try to cover as many of the problems users encounter as possible.

2. Don’t document everything. Instead, focus on the context of the user’s problems.

Avoid the trap of trying to provide “complete” instructions that don’t address problems users will likely have. Long introductions, tables of buttons, menu explanations, and other information not directly focused on the context of users’ problems will lead to unnecessary information glut.

3. Put help where users perform tasks.

Users need help in the application, so that’s where the help should appear, not in a separate training system. When you separate learning from work, users are less likely to stop work and turn to another system to learn. The tasks they do and the help for those tasks should be integrated in the same user interface.

4. The research about the usability of help is that people don’t use help.

Research about how people use help often specifically prompts them into a help file, but the natural tendency, without these prompts, is for users to ignore the help altogether.

5. Avoid obvious instructions.

If you can figure something out on your own, so too can the users. Let your help focus on the true problems that users will encounter. Look for points of paint and information gaps on each page. Ask yourself, where am I getting stuck? Where will users get stuck?

6. Search results are a great opportunity to include help.

An empty search results set is a perfect place to include links to help, such as FAQs or top problems, because users are specifically looking for help content. Many times help authors neglect this space.

7. Quick reference guides are read more than marketing material.

Users are more apt to read quick reference guides than marketing material. If you need to get a product message across, it might find more readership embedded in the quick reference guide.

8. Phrase help links as short questions in the interface.

Help links and buttons are practically invisible to the user. But if you phrase your help as short questions in the interface, users are more likely to click them. When you do this, be selective about how frequently you implement the question links.

9. Tools and technologies can distract you from what matters most: the content.

Sometimes spending too much time implementing bells and whistles that tools provide (for example, javascript drop-downs and custom skins) can remove your focus on  the content. DITA allows you to refocus on the content, since you no longer can control formatting (once you set it all up).

10. Almost everyone has a microphone for their computer.

This is the fourth podcast I’ve recorded that’s a “double-ender technique,” where both the interviewee and I record individually on each of our machines in Audacity and then I overlay and sync the two tracks. I’ve found that almost everyone seems to have a microphone and doesn’t have trouble recording in Audacity. Previously, I’d assumed this technique required too much from the interviewee.

Additional Resources

• “Straight Talk: Surviving Tough Times as a User Assistance Writer”
• UX Matters
• Mike Hughes’ blog

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Let me explain. When the user clicks a context-sensitive help link, a help window appears, as it should. But suppose the user doesn’t close the help window, but instead clicks back to the application. The help window minimizes. Now the user then clicks another context-sensitive help link. The new help topic loads in the existing help window, sure enough, but that help window remains minimized. The minimized help window doesn’t automatically come to focus on top. As a result, the user thinks the help link is broken.

Fortunately, the solution is simple.

1. Go to C:\Program Files\MadCap Software\MadCap Flare V4\Flare.app\Resources\WebHelp or wherever you installed Flare.
2. Open Default.js in Notepad.
3. Search for window.open( cshString, “_MCWebHelpCSH”, browserOptions + size ); and delete it. Note: If you copy this string from this post, make sure you retype the quotation marks, since my stylesheet renders then as curly quotes instead. The quotation marks should be straight.
4. Insert these two lines in its place:

var newWindow = window.open( cshString, “_MCWebHelpCSH”, browserOptions + size );

newWindow.focus();

Note: See note in step3 about making the curly quotation marks straight. Otherwise it won’t work.

5. Completely wipe away the previously published target and reupload or republish your files.

Now when the user clicks subsequent context-sensitive help links, even if the help window is minimized, it will come to focus on top. Perfect.

Tip: If you use Madcap Flare, I highly recommend that you subscribe to Eddie VanArsdall’s blog: Simplifying Complexity. Eddie is a certified Flare instructor and provides tips about Flare on his blog.

Note: As always, Flare doesn’t support changes to the core files. When you upgrade to Flare 4.2, your changes will be lost. In that case, keep this post handy.

Coding the Javascript Help Link

By the way, if you read Flare’s instructions for implementing context-sensitive help in a web application, the javascript example is generally given as follows:

<input type=”button” value=”Open Help System” onclick=”FMCOpenHelp( 1000, null, null, null );” />

This link creates a button. If you don’t want the button, code the javascript link like this:

<a href=”javascript:FMCOpenHelp (1000, null, null, null);”>Help</a>

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

• New podcasts download automatically when I merely plug it in to my computer and click Sync.
• Its small size allows me to clip it onto my belt and easily hide the headphones in my pocket.
• I can quickly toggle between music and podcasts.
• When I stop a podcast half way in the middle, the iPod remembers where I left off the next time I return to it.

I have my BlackBerry clipped onto the left side of my belt and the iPod Nano clipped onto the right. Yes, it feels nerdy, but it’s also extremely convenient. If I had to dig the iPod out of my backpack every time I wanted to listen to a podcast, or if I had to sit there every morning downloading podcasts, I’d be much less likely to listen. But by making podcasts extremely convenient, I plow through more episodes now than ever.

There’s a lesson to learn here: Don’t underestimate the importance of convenience. If you want to increase the usage of your help material, increase its convenience. Make your help context-sensitive. Provide a one-page quick reference guide. Give the user a search field that returns accurate results, etc. The long printed manual is going out of style not because it’s ugly or long, but because it’s inconvenient.

• In Flare: the good stuff, he explains the features of Flare that he really enjoys, such as being able to integrate his own javascript and PHP scripts directly into the code.
• In Why do we use Flare?, he and a colleague talk about Flare in depth — for about an hour, actually, discussing the little things that annoy them about Flare, such as the visual editor.
• In What does it take to be a technical writer (a carcast), he mentions some key qualities technical writers need, such as a curiosity for learning and understanding how things work.
• In his May 19th Dogcast, he actually gives the podcast while walking his dog. The podcast covers the evolution of help, the need for technical communication, and user psychology.

Although the dogcast started out slow, this was the podcast I enjoyed the most. About 15 minutes into the podcast, he really hit his rhythm and started driving down into the topic that seemed to grip him most: user psychology. Users don’t read manuals. The days where long, printed manuals were standard prerequisites to using technology are gone. People experiment with an application and try to learn by doing; when they need information, they search for information about the task they’re trying to accomplish in that instant. Online help is critical in helping users find a single piece of instruction for an immediate need.

Users are also in a state of anger and impatience when they turn to the help. They’re mad because the software has frustrated them and stopped their work. They don’t want to read a manual. What they really want is someone to explain to them how to do something.

Listening to Alistair’s thoughts on the user’s state of mind made me think about the help we write. Why is it that we often begin a software documentation project by documenting all the tasks that users can possibly do from all the available functions of the software application? We spend the bulk off our time creating written instructions that almost no one wants or reads.

Instead, I think we should be focusing on several key deliverables:

• Audiovisual tutorials or screencasts
• Short getting started guides covering the basics
• Context-sensitive online help

Further, we should begin by getting to know our user — not through a description from the SME or business analyst, but actually contacting the user to determine the tasks they want to accomplish and the format for the help.

The Getting Started guide should walk them through the most common, basic tasks the user will need to perform. This guide should be easy to get through. Alistair says the help should provide immediate rewards to the user. Take them through some quick wins. In the Getting Started guide, you give them easy-to-perform tasks that make them successful.

The screencasts (which should also be short) provide a range of other benefits, such as providing the experience of a friend showing them how to use the application.

The context-sensitive online help gives the user immediate information about the task at hand. The online help also provides a searchable database for answers.

So often we begin with the comprehensive manual in mind, when that’s the last priority for users.

Additional Resources

A few months ago I posted some notes from a Kathy Sierra presentation that talked about the user’s state of mind as well.