Making Ubuntu Help helpful

Launchpad entry: https://launchpad.net/distros/ubuntu/+spec/helpful-help
Created: 2005-04-27 by MartinPool
Contributors: MartinPool, MatthewPaulThomas, JeffWaugh
Packages affected: scrollkeeper, ubuntu-docs, yelp

Summary

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 help.ubuntu.com 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:

EmbeddedHelp: Encouraging upstream to put useful documentationalistic hints directly in their software.
ImprovingYelp: Iterative improvements to the GNOME help browser.
LinkingDesktopToOnlineHelp: Building a useful relationship between help available within the distro and on the web.
TopicBasedHelp: Splitting help pages into small useful chunks.
ExistingDocumentation: We have a huge amount of documentation we're not exposing to users very well, so we need to fix that.

Rationale

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.

Assumptions

When someone is installing or troubleshooting Ubuntu, they:

probably don't have another computer available
don't have the ability to run other programs on the same computer
may not have Internet access.

When someone is looking for help within Ubuntu, they:

are accessing help as a last resort, if nearby humans are not knowledgable enough, and Google is either unavailable or not focused enough
are often frustrated, impatient, and pessimistic about the usefulness of the help
almost always want to search for instructions or explanations, rather than look at tables of contents, tutorials or overviews
will give up if they reach a dead end, even if the answer might be elsewhere
do not care about "books", "chapters", "FAQs", "DocBook", "yelp", or the "Ubuntu Documentation Project".

If people find the help they need, they:

will most likely use it successfully if they can read it while carrying out the instructions in the program alongside
may want to print it out for easier study.

Use cases

Niels is installing Ubuntu for the first time, and has no other computers nearby. Fortunately, the colleague who gave him the Ubuntu CD also printed a copy of the installation guide for him. After installation, Niels looks in the "Internet and networking" section of the Ubuntu Help to find out how to get his dialup connection working.
Sandra has imported her holiday photos into gThumb, and wants to e-mail three of them to her mother. After failing to find this function in the menus, and with no-one nearby to ask, she opens gThumb's help function and searches for "mail photographs". There are no matching pages in gThumb's help, but the help viewer returns a result from the general Ubuntu Help about how to e-mail a file to someone. Following the instructions, Sandra successfully sends the photos.
Claude wants to set up a local Apache server to test Web sites he's developing. He looks in the help for instructions on how to do this. Later, he wants to know how to configure .htaccess files; this topic is not covered in the Ubuntu Help, but the help does link to the Apache page on help.ubuntu.com, which in turn links to the apache.org page about .htaccess.
Tukta needs help using Evolution's calendar. She doesn't like reading help on a computer screen, especially since English is her third language and she is used to Thai translations of help being either non-existent or incomplete. So she is glad to find, at the bottom of Evolution's main help page in Ubuntu, a link to contact details for a paid phone support service.

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.

Comparisons:

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 help.ubuntu.com and paid support services. This can be done as follows.

A distinct but unobtrusive link at the bottom for "Get more help online" should be present at the bottom of all search results, and at the bottom of all pages except those that explicitly opt out. In Ubuntu, this link should open a Web browser to search help.ubuntu.com for pages containing the same search terms (for search results) and/or the page title (for a help page). The link should never break as long as help.ubuntu.com exists, regardless of what CMS it is using in a given year. The link should be greyed out with an explanation if the network is offline (see NetworkMagic).
Distributors may choose to add a further link to the bottom of each page, such as "Get support from name-of-company". They may also customize the "Getting more help" page.

Comparison:

Windows Longhorn's "Assistance Escalation Path"

help.ubuntu.com

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 help.ubuntu.com a superset of the packaged help, rather than a partially intersecting set. help.ubuntu.com 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. help.ubuntu.com 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, help.ubuntu.com 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 help.ubuntu.com, which in turn should link to Xhosa Web forums if they exist.