HelpfulHelp

Differences between revisions 1 and 12 (spanning 11 versions)

Making Ubuntu Help helpful

Created: Date(2005-04-27T09:55:24Z) by MartinPool
Priority: NeedsPriority
People: MartinPoolLead, MatthewPaulThomasSecond
Contributors:
Interested: GregTaylor
Status: BrainDump
Packages: scrollkeeper, ubuntu-docs, yelp
Dependents:
FullSearch(HelpfulHelp)
UduSessions: none

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 faster and more compact, and writing effort should go into pushing properly-written help to upstream applications.

Rationale

Ubuntu is about humanity, and part of humanity is doing our best to help people who are having trouble. Providing useful help makes life easier for people MigratingToUbuntu, helping 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 even have Internet access.

When someone is looking for help within Ubuntu, they:

will access the [http://g2meyer.com/usablehelp/lastreso.html help as a last resort], if nearby humans are not knowledgable enough, and Google is either unavailable or not focused enough
will often be [http://tc.eserver.org/10347.html frustrated, impatient, and pessimistic about the helpfulness of the help]
are almost always wanting to [http://web.archive.org/web/20021213225158/http://world.std.com/~uieweb/online.htm search for instructions or explanations], rather than looking at tables of contents, tutorials or overviews
do not want to look in multiple places for their answer
do not care about "books", "chapters", "FAQs", "DocBook", "yelp", or the "Ubuntu Documentation Project".

If people find the help they need, they:

will be most likely to succeed if they can read it while following 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, he looks in the "Internet and networking" section of the 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 (despite this page not using the word "photographs"). Following the instructions, Sandra successfully sends the photos, despite the originals being 2 MB each and her mother having a mail quota of 5 MB.
Claude is a Web developer wanting to set up a local Apache server to test his sites. 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 [http://httpd.apache.org/docs/howto/htaccess.html 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 the 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 [http://joelonsoftware.com/articles/LeakyAbstractions.html 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 [http://mpt.net.nz/archive/2005/04/11/ubuntu#help 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 accessed from a menu item labelled "Contents", 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 [http://www.useit.com/alertbox/9602.html that place is not on a computer screen]: for example, the screenshots they use are often too large for the help viewer window, and are also [http://64.233.161.104/search?q=cache:Ab7nx7LLa3EJ:www.infomanagementcenter.com/enewsletter/200411/secondary.htm+%22dropped+most+screenshots%22 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, Gimp, and OpenOffice use their own help viewers with inconsistent interface designs. The [http://www.mozilla.org/projects/help-viewer/ 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. At most, 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.

attachment:helpsystem.jpg

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 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 short help embedded into 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 grouped underneath results from the current program's help. Programs should be able to tell the help viewer to search for particular words, protecting against broken links when help is updated independently from the software.

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:

[http://knabedesign.com/articles/applehelp/applehelp.html Designing Apple Help by Kevin Knabe]
[http://help-info.de/en/Help_Info_Longhorn/longhorn_help_pane.htm Preview of Windows "Longhorn" help viewer]
[http://g2meyer.com/usablehelp/gallery/ Gallery of modern help systems]

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.

However, as mentioned above, when people need help they want to look in only one place for their answer. For Ubuntu, this one place should be the help viewer. So if the packaged help does not answer a question, the help viewer should integrate as smoothly as possible with help.ubuntu.com and paid support services, so that looking for help is a single process. This can be done as follows.

A distinct but unobtrusive link at the bottom for "Look for more help online" should be present on all pages, including search results but not including the front page (which should already link to a "Getting more help" section). This link should search help.ubuntu.com for pages containing the search words if there are any, or the title of the current page otherwise. The link should never break, regardless of what CMS help.ubuntu.com is using next week or next year or next decade. 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 for "Get support from name-of-company. They may also customize the "Getting more help" page.

help.ubuntu.com

After asking any nearby humans, many people will search the Web rather than venturing into a program's Help menu.

The most useful troubleshooting techniques are generally to ask a knowledgeable person or group, or to ask Google.

* Google does a remarkably good job of matching synonyms, both because of its own intelligence and because the synonyms are likely to be used in at least some web resources. Few online help systems can correct spelling errors or synonyms.

Obviously not all users have net access all the time, but many do. For people with no net access at all there should be a baseline of documentation loaded onto the machine. Some people have net access only intermittently, or not from the machine where they are trying to use Ubuntu.

* The Help menu contains a link to e.g. a web forum about the product. (Or an irc channel, though IRC has usability problems of its own.) If the user prefers a language other than English ideally it would take them to a forum in that language, which might imply going to e.g. a general Ubuntu Xhosa forum rather than a product-specific English forum.

There is also a role for the help system to teach people how to use these resources effectively: for example, by googling for error messages, filing good bug reports, etc.

Like the packaged help, online help should be task-centered, though there is more scope for tutorials and overview documents.

...