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