In our quest to get more decision-making weight in the organization, the User Education team is putting together a set of standard practices. You may wonder why we don’t already have these. To put it succinctly, we still have to carve out our place in the IT department’s project lifecycle so that at least most projects have a user education component to them. Since there have been only a few of us, we’ve operated mostly by our own judgment, each person doing what he judged appropriate for each project.

We’ve come to realize that if we want our department to take us seriously and give us the place we want, we need to be equipped to justify the decisions we make on what user education products are right for any given project. One of the things I’d like to see happen in our team is to develop a menu of products, each with a specific definition and an explanation of the situation(s) in which we would recommend that product.

I’ve taken a first shot at this. I’d like your help to flesh this list out, the descriptions, and the reasons you’d use each one. In the comments, please let me know what I’ve left out.

Quick Reference Guide: One-to-eight-page guide that contains reference information, repeatable tasks, or some combination of these. Used when users have small number of tasks or will frequently need to refer to charts, tabular data, and so on.

Quick-Start Guide: One or two sheets that explain the steps for setting something up. Could also provide a set of most common tasks. A throw-away document. Focus may lean toward one-time training.

Short Guide: Thirty-to-forty-page document that provides task steps and reference information. Used when there is too much information for a quick reference guide.

› Continue reading…

Bookmark It

Hide Sites

RoboHelp’s WebHelp skins include a mini nav bar in the left pane. It holds forward and back buttons for browse sequences, a sync TOC button, and a button for hiding the pane.

If you’re like me, you don’t use browse sequences, and you set the TOC to sync automatically. As a result, the only button there is the hide (“X”) button, so it looks like the following image:

In this situation, the mini nav bar is mostly a waste of space. If you want to save some space by getting rid of it, here’s how to do so:

1. Open your .skn file.
2. Find and comment out both instances of the following:

<frame name="MiniBar Pane" marginwidth="-1" scrolling="no" id="6" />

3. Find both instances of what looks like the following:

<frameset rows="48,*" >

and change them to:

<frameset rows="100%" >

4. Save the .skn file.
5. Generate and view your WebHelp.

One of the nice things about doing this is your skin file is static, so it will apply these changes every time you generate your WebHelp output.

Note: This is how it works in RH7. If no changes were made in the .skn file for WebHelp in RH8, it should work there too.

Bookmark It

Hide Sites

I’ve expressed dissatisfaction in the past with the traditional tri-pane help format. I think it’s outdated and has gotten such a bad reputation with computer users that it’s too late to change that. So I think it’s time to find other ways to provide user assistance.

A few weeks ago, I got an email stating I was now being followed on Twitter by @helpburner. I thought this could be another technical writer, and I usually check the tweets of people who follow me anyway. Imagine my interest when Mike Stokes, the owner of this account, had tweets mentioning the beta test of a product called HelpBurner.

› Continue reading…

Bookmark It

Hide Sites

I don’t think online help is the wave of the future—it’s more the wave of the past—but I’m still always trying to keep my brain open to ideas for improving it.

I attended a meeting today with the folks I work with in a project portfolio. Our portfolio manager reviewed what the group accomplished in 2009 and showed us what’s coming up this year, including the goals the managers cooked up.

One of the developers demonstrated an application his team built for their customers to use in accessing content in a MarkLogic database. Of course, the application featured robust searching because of indexing and tagging.

This got me asking myself: What if online help could be configured to be context-sensitive in a different way than usual? What if, when the user launches the help system, instead of opening to some assigned help topic, it instead runs a preprogrammed search on keywords assigned to that topic? Then the results display in the help window, and the user can scan the results and choose where to start? Basically, can anticipatory search be done, and would it be helpful?

› Continue reading…

Bookmark It

Hide Sites

I conducted some context-sensitive online help usability testing with four users of a Web application. This post discusses the results (without getting overly academic in tone, I hope).

Objective

I wanted to find out whether and how quickly participants could find given pieces of information and answers to specific questions in two versions of a help system described in this post.

Specifically, context-sensitive topics in the first version have a screenshot giving an example of how the screen can be used, sometimes with numbers corresponding to annotations in the text below. The newer versions of extensive help topics had the screenshot hidden in a dropdown hotspot and details contained in dropdown hotspots instead of being annotated. Specifically, the hotspots were formatted as green, underlined text with a right double angle bracket afterward.

› Continue reading…

Bookmark It

Hide Sites

Documentation doesn’t need a full-blown usability test, lab with one-way mirror and all, but it should have something. That’s one thing I’ve been working on this week with a particular help system I described in my last post.

When doing usability testing on documentation, keep the following things in mind. (These apply to any type of usability testing, actually.)

1. The participant isn’t being tested—the documentation is. Make this clear to the participant. You may even want to put it as simply as, “You’re not being tested. I am.” You want to observe how a person interacts with the content. The participant will face no adverse consequences for not successfully completing a task.
2. Come up with scenarios and tasks where the context makes sense to the users. Similar to examples used in documentation, if the situations you present don’t make sense in the participant’s world, she’ll spend time getting confused or correcting you. Think through the context of the tasks you’re using to be sure it holds up.
3. The participant should speak out loud so you can record thoughts, feelings, and reactions. It’s okay in informal testing to ask, “What are you thinking right now?” or “Why did you choose that option?”
4. Any pause in movement of more than a couple of seconds means the user has to ponder what to do. That suggests a potential usability problem.
5. Put together follow-up questions to find out how the participant feels after interacting with the documentation. Of course, you’re looking for objective data and observations; however, one of the important things to find out is the impressions the participant comes away with regarding the documentation and the product. Those impressions could very well affect how much the person wants to have anything to do with your organization and its products.
6. It’s okay for the participant to give up. People do that. Explain this to the participant. Usability testing is about seeing whether people can complete tasks successfully most of the time (or ideally, all of the time). You may wonder whether telling the user that she can give up is somehow planting that idea in her mind. But if the person were on her own and trying to use the documentation, she would think of giving up just as quickly.

Bookmark It

Hide Sites

In one application I work on, I recently added some text to the context-sensitive help topic for a screen that allows financial secretaries to make a payment. The text described what to do with a particular control that had been added to the screen.

Because of the many variables involved in making a payment in various countries around the world, this screen has become functionally dense, leading to a help topic that I finally decided had become cumbersome. The bulk of it was a procedure for filling out the information, but in between steps was a lot of “if you need to do X, enter Y” and such things. Some of those extra explanations were only a couple of extra sentences, but added together, it was a lot of content being spewed at the user.

This is a Web application, so we don’t have field-level help. The growth of this help topic led me to imagine that if a user clicked Help for information about one particular field and had to slog through the text in that topic, they wouldn’t get very far before giving up. That much information punching you in the face would be enough discouragement without even beginning to scan it.

I needed a different approach.

› Continue reading…

Bookmark It

Hide Sites

The prevailing perception of printed documentation is that it’s a goner. Because of the work I’ve been doing on quick reference guides lately, I disagree; I think people don’t necessarily want everything online, but at the same time they just don’t want a thick manual they’d sooner use as a booster seat for their toddlers at the dinner table.

› Continue reading…

Bookmark It

Hide Sites

A couple of years ago, I was using RoboHelp X5, a help authoring tool (HAT) that was several years old. In the software industry, letting your product go that long out of date is bad for business. RoboHelp still had a lot of users for a couple of reasons: Many had used RoboHelp and its predecessors for years, and there weren’t very many alternatives.

Macromedia had shelved RoboHelp and disbanded the product management team and RoboHelp developers in 2005. Mike Hamilton, the product manager, left about that same time. On the Internet, Hamilton criticized Macromedia, and by extension Adobe Systems, who had purchased Macromedia. He announced his joining a new company, MadCap Software, and that they would be releasing Flare, their flagship product and new HAT.

› Continue reading…

Bookmark It

Hide Sites

In a previous post, I wrote about the irony of technical writers not following directions. It made me think about the expectations I bring to online help or a set of printed instructions written by someone else. I think that because of their profession, technical communicators approach documentation differently than users in other fields.

Personally, I come to others’ documentation with a set of expectations. I’m critical at the same time that I’m sympathetic.

› Continue reading…

Bookmark It

Hide Sites