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
- The Docs Project has a wiki page on GNOME Live
- The GNOME Documentation team uses the new Mallard XML format for writing help
- Source files are stored on git.gnome.org
- general GNOME Desktop help in http://git.gnome.org/browse/gnome-user-docs
- help for applications in their
/help/directories, e.g., http://git.gnome.org/browse/empathy/tree/help/C
- GNOME help is available in HTML: http://library.gnome.org/users/
- Bugs and patches are tracked with bugzilla.gnome.org
- Discussions happen via email — email@example.com and IRC — #docs on irc.gnome.org (GimpNet in Empathy)
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.
- Help usability is an active research field.
- There are several types of sources:
- journals (such as Technical Communication) and conference proceedings (such as SIGDOC)
- practical articles and resources in technical communication magazines
- books, both monographs like Carrol’s Minimal Manual and collections like The Art of Human-Computer Interface Design
- guidelines for commercial and free projects, such as the GNOME style guide http://developer.gnome.org/gdp-style-guide/stable/index.html.en
- Each stage of the documentation process has its own research area, e.g.:
- research of typical help use patterns
- design of documentation
- organization of the writing process
- evaluation methods, such as heuristics and testing
- There are many websites with resources on the subject, but only some of them are more-or-less current
- Online general usability resources:
- Help / documentation usability resources:
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
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.
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.
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
- 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.
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.
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.
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.
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 :)
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!