Skip to content
July 29, 2011 / Nita

GOPW Halfway Report

Incredibly, my first GNOME summer is already halfway through, so it’s time for a progress report. Here are some of the things I’ve learned and the sub-projects I’ve worked on so far.

How GNOME Documentation is made

All in all, the team seems great, and the tools are used effectively, although some of the process documentation and the style guide could be updated for the newbies’ benefit.

Literature overview

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”.

Better help checklist draft

  • Compiled research results, practical guidelines and evaluation heuristics from 6 articles
  • Sorted them by theme (such as structure, language, navigation)
  • To Do:
    • Categorize checklist items by level of application (entire system, section, topic)
    • Improve the wording for better usability
    • Finish writing a short explanation for each item
    • Send the draft to gnome-doc-list for review
June 23, 2011 / Nita

Empathy help: Introduction

This is an introductory post in a series on Empathy documentation.

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:

  1. finally find the answer to one of my old questions — “Can Empathy merge contacts?”;
  2. 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.

Reading the help page

If all goes well, we end up on the page “Combine and separate contacts“. Although it’s short, it contains:

  • breadcrumbs — I’m not lost yet, but if it happens, it’s clear where to look
  • a definition — now I know the result of merging contacts is called a “meta-contact” (although I wouldn’t have found the page with that keyword)
  • an example — very helpful for the unfamiliar with the concept of merging
  • how-to steps — the most prominent part of the page, which is good, since that’s what I came for!
  • a note on protocol priority — I’ve always wondered about that
  • how-to steps to undo the action — “What if I mismerge?”
  • links to the parent topic and other tasks — good, although in this case, I wonder how they are related

All in all, I found it a very helpful page.


Mission accomplished! It works, except with the “People nearby” account (and I’m not sure why).

Mission 2: Why won’t it connect to people nearby?

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)


  • 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.

Helpful resources

Empathy documentation online — alas, without the insta-search
A comprehensive guide to Empathy for Pidgin powerusers

June 17, 2011 / Nita

Better help: General guidelines

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.

An expert giving you a kindly stern look.

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)
  • complete—include task instructions, definitions, requirements and examples
  • 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.

May 27, 2011 / Nita

Who’s afraid of the big bad help?

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.

A friendly demon enthusiastically reading a huge book.

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.

  1. 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
  2. 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.


Andrade, O. D., Bean, N. & Novick, D. G. (2009). The macro-structure of use of help. In Proceedings of the 27th ACM international conference on Design of communication (SIGDOC ’09), 143-150.
Carroll, J.M. and Rosson, M.B. (1987). The paradox of the active user. In J.M. Carroll (Ed.), Interfacing Thought: Cognitive Aspects of Human-Computer Interaction.
Grayling, T. (1998). Fear and loathing of the Help Menu: A usability test of online help. Technical Communication, 45, 2.
Novick, D. G., & Ward, K. (2006). Why don’t people read the manual? In Proceedings of the 24th Annual ACM International Conference on Design of Communication (SIGDOC ’06), 11-18.

GNOME thoughts

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):

  • Nautilus, Empathy, desktop (no window) – the appropriate table of contents in yelp
  • Blender, Pidgin – the manual in the default browser
  • Liferea, Zim – the manual in the application itself
  • OpenOffice, Gimp – the context-appropriate page in the app’s own help system
  • Inkscape, Network manager – nothing (although the help does exist and can be accessed by other means)
  • Lokalize, BasKet Note Pads (KDE apps) – an error message

In most cases, you do end up with decent documentation on your screen. But it feels like a bit of a gamble, which might prevent you from relying on help as a matter of course.

May 20, 2011 / Nita

Reached by GNOME Outreach

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:
5 people in documentation, 2 in art, 2 in accessibility and 1 in localization.

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!