HelpfulHelp

Differences between revisions 8 and 9

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:

already have Ubuntu installed
are usually looking for a quick answer, not a tutorial
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"
will often be frustrated or angry, having spent considerable time trying to solve their problem already
will have accessed the [http://g2meyer.com/usablehelp/lastreso.html help as a last resort], with nearby humans not being knowledgable enough, and Google being either unavailable or not focused enough
will be pessimistic about their chances of the help being helpful.

If people find the help they need, they:

will probably 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,
Sandra has successfully imported her holiday photos into gThumb, and now she wants to e-mail three of them to her mother. She trawls through gThumb's menus but fails to find anything to do with e-mail. So she opens gThumb's help function and immediately searches for "mail photographs". There are no matching pages in gThumb's help, but the help viewer also returns a result from the general Ubuntu Help about how to e-mail a file to someone (even though this page doesn't use the term "photographs" in its visible text). Following the instructions in this page, Sandra successfully sends the photos, despite the originals being 2 MB each and her mother having a mail quota of 5 MB.
...
...

State of the help in Ubuntu 5.04

From the terminal, 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 Ubuntu's help is a program with the unfortunate name "yelp". (In theory that name is never visible, but in practice [http://joelonsoftware.com/articles/LeakyAbstractions.html of course] 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]. In general, 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 that place is not on a computer screen. Yelp's interface is also cluttered by the reference manual mindset, with a table of contents and previous+next links taking up valuable screen space.

For added fun, Firefox, Gimp, and OpenOffice use their own help viewers with inconsistent interface designs. The Firefox and OpenOffice help viewers are too complex to fit comfortably on one side of a screen while following instructions on the other side, 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 decent integration between the help viewer, the software it is providing help on, and other sources of support. Programs can launch the help viewer at a particular page, but the reverse is not true; the help viewer cannot tell a program to highlight a particular control in a window. And with the notable exception of Firefox, programs do not offer any suggestions of where to get help if the local help documents are not enough.

There is a lot to be improved.

How help should work

Ideally, the process of helping someone use software should be a smooth continuum between the software itself, the help viewer, the Web, and paid support services.

attachment:helpsystem.jpg

Making software easier to use to begin with is outside the scope of this spec. However, 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.

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. Programs should be able to tell the help viewer to search for particular words, protecting against broken links when help docs are updated independently from the software (better for the help viewer to open at search results than to open at an error message).

The help itself should concentrate on giving people step-by-step instructions on how to do things, intermingled with occasional topic overviews. Where appropriate, a help page should end with a list of links to related pages.

As part of the teaching process, the help viewer should be able to tell GTK to highlight an element in a program's window -- ideally, by drawing a translucent ring around it. This mechanism should be smart enough to first draw a ring around the program's launcher if it is not running, waiting until it is; then to draw a ring around the window's button in the window switcher if the control is not immediately visible, waiting for you to bring the window to the front; and if the desired element is a menu item, it should guide you to the parent menu and (if applicable) submenu first.

If the local help cannot solve a problem, it should link to help.ubuntu.com without people having to retype their search words.

Web integration

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

* Suggestions and opinions from individual users can be posted direct to web forums. User-written documentation typically addresses user concerns in their own language much better than most help files do.

* Web forums and documentation can be updated more rapidly than online help.

* 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 system should integrate with these resources. By doing so, we may redeem the bad reputation of online help, and create a more virtuous cycle of interest in improving it. Possibilities:

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

help.ubuntu.com

Implementation

Breezy suggestions

These are not confirmed bounties, only suggestions. If you're looking for a bounty, come back when this spec has reached Approved status.

In approximate order of importance:

Write general help for Ubuntu following the assumptions above (see [http://ubuntu.com/wiki/LocalHelp LocalHelp]), and have this help appear immediately when the "Help" menu item is chosen.
Set up a bounty to add search to yelp.
Set up a bounty to add a print function.
Rename yelp to HelpViewer or some similar human-understandable name.
Set up a bounty to get Gimp using the standard help viewer.

Future work