To sum up my impressions, new theories and tools for writing help emerge all the time, but eventually some principles gain wide acceptance. So, at least in some aspects, documentation “best practices” exist, and we can use them.

Also, one of the big problems for help is that many people who would benefit from reading it don’t feel it’s worth the effort. On the bright side, the content and structure of the new GNOME help is already geared toward easier and quicker use. To improve this situation, we’ll need to ensure complete coverage, iron out any usability wrinkles, make getting context-specific help really easy, and give it some time.

A look at Empathy help

The documentation was fairly easy to read and navigate.

It addressed the questions I had, although it couldn’t solve a particular (rare) problem.

For a more thorough review, I will use a checklist derived from the literature. I’m tentatively calling it the “Better help checklist”.

Empathy is the multi-protocol instant messaging (IM) client that replaced Pidgin as the default in GNOME 2.24 and Ubuntu 9.10 “Karmic Koala”. I’ve been a Pidgin user since the times when it was called Gaim and my PC was running Windows. Empathy, on the other hand, I first encountered during an Ubuntu localization sprint, right after the big switch. Translating the settings and preferences, I thought, “Hmm, the original strings could use some work — must be a new app”.

Today, Empathy is all grown up, but we’re not exactly best pals yet. “Where are my buddy groups? How do I join a chatroom? Can it merge contacts?” I wondered on occasion. So, in this post, I’ll use my last chance to approach Empathy help with the mindset of a “typical user” — hopeful, a little frustrated and somewhat confused.

First impressions

Frankly, since Empathy is relatively new and fairly non-verbose, a few months ago I didn’t expect it to have documentation at all. But now, I hit F1, and voilà — a nice long menu of help topics. In contrast with traditional manuals, including GNOME 2 help, the topics are not numbered, suggesting a non-linear structure, and each one has a short description that clarifies the link text.

The GNOME help viewer, Yelp, works like a simplified web browser. The layout is clean and smooth, as if to reassure me that the docs are easy to read and up-to-date.

Looks great so far! Now let’s try using it. I gave myself two missions:

finally find the answer to one of my old questions — “Can Empathy merge contacts?”;

fix an issue I was having at the moment — the “People Nearby” account keeps trying to connect unsuccessfully.

Mission 1: How do I merge contacts?

Finding the help page

First, I tried scanning the links for something appropriate. Aha, there it is, under “Contact Management” — and even above the “fold”:

Yelp 3 also has a neat search feature. The only potential problem with it is that some people might not notice it’s there — until you click in the text box, the feature is not obvious (except to avid users of modern web browsers, who are used to enhanced — or even “awesome” — location bars).

The search provides instant results as you type. Unlike in Yelp 2, the results are limited to the currently active manual, which helps keep the results list short and relevant. Here’s my first attempt, typing “merge” in the location bar:

“Combine” also worked fine, but not “join”, “unite” or “group”. Unfortunately, I also managed to crash Yelp by hitting Enter after typing the search term. Even more unfortunately, it’s not just my unique tester’s talent: 699990, 706337, 710089.

Some scrolling and scanning revealed that, in line with my expectations, “troubleshooting” topics are found near the end. In this case, the link is “Problems connecting to an instant messaging service” under Common Problems.

The only textual manifestation of the issue in Empathy was the perpetual “Connecting…” status in the account properties, and typing “conn” in the search box also worked quite well.

On the page, I was presented with a list of different connection issues, none of which seemed like a perfect match, but the last one came closest.

On the issue subpage, the main content is a list of steps. They seem quite sensible, although I wondered if making sure the Enabled checkbox is selected should come earlier, as step 3 instead of step 5.

The solution didn’t work for me, but it turned out to be a fairly specific problem (avahi-deamon doesn’t run by default on Fedora 15 systems installed during the early beta phase)

Conclusions

Empathy does have documentation!

Yelp looks good

the incremental search is a neat feature, although it’s fragile on my system

the help pages are often task-oriented and provide short and helpful answers

merging contacts in Empathy is easy (although not as intuitive as in Pidgin)

the connection problem solving guide covers the most common reasons, but doesn’t provide tips for handling more advanced issues

This concludes my first, user’s-eye-view encounter with Empathy help :) I used Empathy 3.0.2 and GNOME 3.0.1 on Fedora 15.

In the previous post about users’ lack of love for help, I promised something more hopeful, including guidelines distilled from more usability studies and experts’ recommendations. So, here are some qualities of good help, with short explanatory notes.

Experts strongly advise you take expert advice.

In terms of content, good help is:

relevant—address the common questions and problems that real users have (use feedback, support requests and studies)

scannable—use headings, lists and tables, but not too many links or emphasized words

readable—keep it short, clear and easy on the eyes

self-contained—try to make every page useful on its own

In terms of use, good help is:

right there—provide intuitive ways to access help wherever it’s needed

context-specific—let users avoid searching with tooltips and relevant links in dialogs and menus

searchable—index the content with popular synonyms (but match the UI in text)

easy to navigate—minimize the number of organization levels, consider adding a “sitemap”

non-intrusive—don’t interrupt the user or hide their work area

The good news is that some of these guidelines already match the current design and writing style of the GNOME Documentation Project. Others, not so much. In the next post I will take a more detailed look at Empathy help in GNOME 3.

Despite having used Inkscape for years, I learned a lot more about it while writing a guide to vector graphics. Why? Among other things, I finally read the Inkscape manual. After all, why read when you can jump in and draw, discovering the features in the process?

In turns out that typical users—people using software to do their job—rely on a similar strategy. In 1987, John Carroll and Mary Beth Rosson described what they called “the paradox of the active user”—the fact that, due to being focused on the end-product and unwilling to waste time, people avoided the very documentation that would have helped them be more productive in the long run.

Studies show: this is exactly what users don't do.

Instead of reading the manual, users tried to apply their previous knowledge, used trial and error, and sometimes asked others for help. If they did start reading, they wanted to try out the features right away, skimmed and used heuristic reasoning to jump to conclusions. Presumably, this gave them better chances of quick progress on real tasks, but it also resulted in higher risks and a failure to take advantage of useful functions.

Later studies (e.g., Grayling 1998, Novick & Ward 2006) confirmed that looking up help topics is often users’ last resort, and highlighted specific issues that make help less attractive, which can be divided into two classes.

Insufficient usefulness:

missing information

content that doesn’t answer the right questions

too basic or too complex explanations

uncertainty and missing help topics in the “no man’s land” between software

Insufficient convenience:

no obvious and easy to use mechanism for accessing relevant help

navigation and searching difficulties, including mismatched vocabulary between users and developers

long, hard-to-scan text

help windows or pop-ups interfering with work

In the process of searching for a solution, people frequently switched between recalling their previous experience, studying the interface and trying things out, and searching or asking for help (Andrade, Bean & Novick 2009).

To address these issues and adapt the help system to users’ exploratory learning strategy, help usability researchers developed new designs and recommendations, which will be the focus of my next post.

I think the current GNOME users are more likely to use some form of help or documentation than “typical” users. After all, most of the subjects in these studies were users working with systems running Windows and whatever productivity software their employer chose to install, possibly not interested in spending any of their free time anywhere near a computer.

Many people choose free software because they enjoy learning and tinkering, understanding the system and using the best methods, in contrast with the end-product focus of Carroll’s “active user”. In addition, the sense of community that free software projects encourage can counteract the feelings of alienation and helplessness that some new users experience with computers. And, of course, users of the command line learn to favor help over trial and error :)

However, since GNOME’s target audience is wider than its current user base, it makes sense to aim for more universal usability, including a help system that even the help-phobic would love.

On the less bright side, since free software is made by different developers and communities, the overall documentation experience can be quite uneven. For instance, here’s what you get by pressing F1 in different windows on my system (Ubuntu 10.04 Lucid Lynx):

Hello GNOME! It’s me, Nita — a 26-year-old biology student and free software enthusiast from Riga, Latvia. I’ve done some web development, software testing, localization, editing and LaTeX markup, and written a couple of user manuals. And now, I’m in the GNOME Outreach Program for Women.

My project involves help usability research for the GNOME Documentation Project. I think this is a good time, as the docs are undergoing major developments:

in the approach, moving from old-school manuals to topic-oriented help;

technologically, thanks to Shaun’s active development of help tools;

and, of course, in their content, due to the rapid evolution of GNOME :)

In fact, it seems that most non-GSoC GOPW participants will be working on documentation-related things:

For the first phase of my usability project, I’ll be asking questions like

When do people use help? Why don’t people use help? How do people learn to rely on help, instead of search engines, forums or friends?

What makes help good / useful? How do structure, content, style and technical features contribute to its usefulness?

What is a good way to assess the usefulness of a given help system?

scouring the literature and the web for answers, and posting some of my notes here (hopefully with less silly illustrations).

I’ve been reading everyone else’s posts on Planet GNOME, and it’s a joy to be a part of such an active and friendly community. Thanks to my partner for encouraging me to apply, to the marvellous GNOME coordinators, and to my mentor, Phil Bull. And good luck to all GOPW and GSoC participants!