Making Ubuntu Help helpful


Ubuntu offers vast opportunities for improvement in the quality, targeting, and presentation of its help and documentation. For Breezy, code effort should concentrate on adding search and print functions to the help viewer, and writing effort should concentrate on and local help for Ubuntu in general. After Breezy, code effort should go into making help presentation more compact and integrated, and writing effort should go into pushing properly-written help upstream.

This informational spec has been split into a number of smaller implementation chunks:


Ubuntu is about humanity, and part of humanity is helping people who have lost their way. Providing useful help makes life easier for people MigratingToUbuntu, helping to increase market share. And help that integrates well with external support services could also increase revenue for distributors of Ubuntu and derivative operating systems.


When someone is installing or troubleshooting Ubuntu, they:

When someone is looking for help within Ubuntu, they:

If people find the help they need, they:

Use cases

State of the help in Ubuntu 5.04

From Ubuntu's Terminal program, manual pages are available with the usual man and apropos commands -- good if you're wanting to know how to invoke individual programs, and if you're one of the small percentage of people who are comfortable with the terminal (see CommandLineDisintegration).

For most people, however, their primary access to help is a program with the unfortunate name "yelp". (In theory that name is never visible, but in practice it is -- in the About box, in the Package Manager, in the System Monitor, and in error messages.) By default, a button for accessing help appears on the Gnome panel, but it does not look like a button and people may not realize what it is for. Once people do open the help viewer, its interface is fairly simple (if a bit too large), but its categorization and contents are quite unhelpful. It assumes that you already know (a) what program you want to use and (b) where that program fits in the Gnome taxonomy, neither of which are usually true. Compounding the problem, there is no search function.

Most individual programs offer their own help, which is good; but it is usually hidden in the Help menu as a "Contents" menu item, which is not obvious. Help is written as a set of "books" with "chapters", often taking the form of a depth-first traversal of the interface, rather than actually offering help on likely tasks. Such reference manuals have their place, but that place is in print, not on a computer screen. For example, the screenshots they use are often too large for the help viewer window, and are also likely to be confused with the actual interface. Yelp's interface is also cluttered by the reference manual mindset, with a table of contents and previous/next page links taking up valuable screen space.

Firefox, OpenOffice, and Gimp use their own help viewers with inconsistent interface designs. The Firefox and OpenOffice help viewers are too complex to fit comfortably alongside the program they're providing help on, but they have the advantage of offering a working search function. Gimp's help viewer is more compact than yelp, but is nevertheless harder to use. None of these help systems have adequate integration between the help viewer, the software it is providing help on, and other sources of support. However, programs can launch the help viewer at a particular page, and Firefox's front help page links to online support resources.

How help should work

Ideally, the process of helping people use software should be an integration of the software itself, the help viewer, the Web, and paid support services.


Embedded help

Help writers should be active in reporting bugs which, when fixed, allow a help document to become simpler or to concentrate on likely problems rather than on basic use. Since people other than programmers are highly reluctant to use anything in the Help menu, software authors should be encouraged to add help tips (including explanations of why controls are unavailable), hints and examples for form elements, and other embedded help in dialogs and rarely-used windows.

The help viewer

The help viewer should be, by default, compact enough to fit comfortably alongside the program it is providing help on. It should be easily searchable, with results being returned despite misspellings and use of synonyms, and results from the general Ubuntu Help being grouped underneath results for the current program. Programs should be able to tell the help viewer to search for particular words, a less fragile alternative to linking to individual pages.

The help itself should concentrate on giving people step-by-step instructions on how to achieve things and how to solve problems. Where appropriate, a help page should end with a list of links to related pages or well-crafted searches. (These links themselves should not be indexed for the search function.) As part of the teaching process, the help viewer should be able to tell GTK to highlight an element in a program's window by drawing a translucent ring around it.


Web integration

People experienced with Ubuntu can, and do, post help and suggestions to Web forums and wikis. While upstream help is in its current state, such DIY documentation will often answer questions in non-developer language better than most help files do. Online documentation can also be updated more easily than packaged help, and can continue to be updated after an Ubuntu release.

Because people are very likely to just give up if they do not find the answer on the first path they follow, the help viewer should integrate as smoothly as possible with and paid support services. This can be done as follows.


Many people will search the Web for answers without even looking at the packaged help. While the help viewer's search function remains either non-existent or primitive, the Web may even produce better results, because search engines recognize synonyms and misspellings more thoroughly than the help does.

These people should be catered for by making a superset of the packaged help, rather than a partially intersecting set. should have a slight bias towards information that may change from month to month (such as how to install support for RestrictedFormats), while the packaged help should have a slight bias towards information on how to connect to the Internet or use programs offline.

Like the packaged help, online help should be well-written and task-centered, though on the Web there is more scope for tutorials and overview documents. should also provide links to Web forums and IRC channels, with advice on how to use them; and offer tips on how to search the Web for error messages, file good bug reports, and so on.

Like the packaged help, should automatically display in your preferred language, with help being written in parallel in multiple languages. For example, if you are using Ubuntu in Xhosa, the help viewer should link to the Xhosa area of, which in turn should link to Xhosa Web forums if they exist.


Future work

In approximate order of importance:

See also


CategorySpec CategoryDocteam

HelpfulHelp (last edited 2008-08-06 16:16:34 by localhost)