HelpfulHelp

• 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 avoid confusion and annoyance on the part of people using the system.

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:

• have already installed Ubuntu
• 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.

In short, there are vast opportunities for improvement.

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.

Software

• Ease of use
• Tooltips
• Examples
• Explanations and tips

Integration between software and the help viewer

• Opening the help viewer to specific pages
• Opening the help viewer to search results
• Highlighting controls

The help viewer

• How do I...
• Tell me about... (rarer)

Integration between the help viewer and the Internet

• links
• updating signed help from remote source?

Internet

Integration between the help viewer and paid support

Paid support services

Unsorted notes

• Give a brief summary of what the program is about and how to do the task they seem to be trying to do at the moment.

• Take them through some trouble-shooting questions if they seem to be having trouble.
• Link in to the support/bug reporting system.

• See also AutomatedProblemReports.

• See for example [http://blogs.msdn.com/jonathanh/archive/2005/04/11/407484.aspx this post about web search vs online help in MS Office].

• When an error message is shown, there is a link to help with troubleshooting information and a place to submit a support request/bug.

• http://ubuntu.com/wiki/DocteamProjects

• http://g2meyer.com/usablehelp/gallery/

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:

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

2. Set up a bounty to add search to yelp.
3. Set up a bounty to add a print function.

4. Rename yelp to HelpViewer or some similar human-understandable name.

5. Set up a bounty to get Gimp using the standard help viewer.

Future work

In approximate order of importance:

• Hide or remove the table of contents frame from the help viewer.

• Make the help viewer toolbar icons-only, regardless of "Menus & Toolbars" setting.

• Implement the ability for help docs to launch programs.
• Add index-based spelling suggestions to the search function.
• Get Firefox using the standard help viewer.
• Implement highlighting of controls (requires XOrg Composite + Damage).

Data preservation and migration

Outstanding issues