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

It’s funny when those little everyday experiences make you think about your job in a little different light.

I took the week off for the Thanksgiving holiday. My wife and I were doing some much-needed shopping in a mall at the beginning of the week and stopped at the food court for lunch. When I tried to open a ketchup packet by tearing off the corner, I made a small mess (didn’t get any on my clothes, fortunately).

Giving me a bit of a ribbing because of my profession, my wife said, “You didn’t follow the instructions!” and pointed to where the opposite corner had the dotted line and the words “Open here.”

“I didn’t see the instructions,” I replied.

› Continue reading…

Bookmark It

Hide Sites

Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment.

Skill 1: Topic-Based Writing

Before I describe this one, I need to point out that yes, writing isn’t exactly planning; writing is what a technical writer does after planning. Writing is a rubber-meets-the-road activity.

True, but the project management applies in the way that you plan to write. I heard it said once that DITA is perfect for Agile environments because the way writers chunk information in that scheme allows that information to be dispensed from a single source into whatever output happens to be needed at a particular time. In short, it allows writers to quickly respond.

If I could substitute “topic-based writing” for “DITA” here, I would add that another great benefit is that writing in small topics allows you to keep pace with development and to release documentation in step with the application updates. Small topics give you less work to do in the iterations or sprints and enable you to mark your progress more regularly. So plan to write small in general and then adapt as needed.

› Continue reading…

Bookmark It

Hide Sites

While doing some work documenting an internal face on a third-party application for a specific set of users, I came across what seemed a superfluous help topic for that application. It looked something like this (going from memory here):

You can delete an instance if needed.

• To delete an instance

In the search, where I came across this topic, right next to each other were listed “Deleting an instance” and “To delete an instance.” If you were looking for the instructions for deleting an instance, which one would you pick? If you thought about the nuances of the phrasing, you might pick the second. But when you have a task to get done, you’re not thinking about nuances of language. You click the most likely candidate.

My guess is that the help author had a structure for categorizing topics, and the instructions for deleting an instance ended up alone in a category. That’s just a guess. But it made me think that if I’m right, then the organization of the help was too strict.

When planning a set of documentation, don’t make the organization so strict that you can’t leave out superfluous topics like this. Allow yourself the flexibility to cut to the chase when it’s appropriate.

Bookmark It

Hide Sites

I had a funny idea about the writing process. I was talking to a colleague about the steps he takes to create a video tutorial, and he said he uses his online help content to produce the voiceover script. I haven’t done it that way myself because I think I have this concept that my help text isn’t conversational enough to work as voiceover.

That made me wonder, though, if I could reverse this order to write help (or other types of documentation). How good would my help text be if I inserted a step in the process where I recorded myself just talking about the feature or task that I was going to write about? I could talk as if I were explaining it to a friend or coworker. Then I could use that conversation to write up the content.

› Continue reading…

Bookmark It

Hide Sites

Recently I took some material from the latest release notes and added them to the help system. It was the kind of information that was timeless, rather than topics that explain what to do (or what not to do) until the next release and so on.

As I categorized this information and added it to the table of contents, I realized that what made sense in the topic titles in the context of a TOC or list (or a sheet of release notes) didn’t necessarily make sense on its own. For the sake of brevity, I had omitted some words that were actually essential if the title was all the user had to go on in order to decide whether to explore that topic.

As a hypothetical example, part of the TOC could have looked something like this:

Credit Cards
>> Applying for a Card
>> Making Monthly Payments
>> Viewing Your Current Balance

If this were to appear in a larger set of documents (rather than something that’s exclusively about credit cards), it wouldn’t be clear just from the titles of the topics what kind of card or even what kind of payments and balance are being talked about. The user would have to drill into those topics if coming in from some non-contextual way to see if it’s relevant to his objectives rather than determining it just from the title.

So of course, I had to go back and change some topic titles. These days when we present information chunked in small topics, the titles should be self-contained and give enough information to help the audience see in a second whether it’s relevant.

Bookmark It

Hide Sites

One of the things I would really like to see tech comm tools do is gracefully handle text boxes across formats. If you ever anticipate having to move content from a HAT to some other format, there’s little incentive to do anything other than a dull, single flow of content. No sidebars using divs because they don’t move well into other file types. I understand that in Flare, divs move well into a PDF, but not into Word.

I would like to see divs in HATs convert into text boxes in Word and into text frames in InDesign (or FrameMaker if that’s your bag). I realize this is mixing vendors and file formats something crazy. But that’s why I’m calling this my “Christmas wish.” I don’t expect it to happen. It would just be really slick if these aspects of various document creation tools moved text boxes nicely when exporting or importing.

Bookmark It

Hide Sites

Sarah O’Keefe (@sarahokeefe) of Palimpsest tweeted today that according to a webinar she was attending by Ellis Pratt (of Cherryleaf, @ellispratt), nine times more people visit help websites than traditional help systems. This really got me thinking throughout the rest of the day.

If It Looks Like a Help System…

Why would people be nine times more willing to go to a website than an online help system? Since this may have been explained in the webinar but all I have regarding it is Sarah’s tweet, my initial guess is that people tend to think a help system is static and easily outdated (they don’t know about the Agile technical writer?), while a website is fresh and frequently updated. Whether those things are actually true isn’t as important as the fact that the audience perceives them as being true.

This led me to thinking that all is not lost for help authoring tools, though. I’m sure with some effort, I could make an online help system look like a website. Of course, it would take WebHelp to do that convincingly, so this approach may not be possible for all software products.

The first step would be to use some term other than Help. Next, get rid of that traditional side pane, one of the dead giveaways that you’re looking at a help system. RoboHelp and Flare, and maybe others, enable this.

Part of the problem here, though, is that the side pane contains much of the navigation. So it would take putting on the Web designer hat to work out the best way to offer navigation through the help.

› Continue reading…

Bookmark It

Hide Sites