HelpfulHelp

• Created: Date(2005-04-27T09:55:24Z) by MartinPool

• Priority: NeedsPriority

• People: MartinPoolLead, MatthewPaulThomasSecond

• Contributors:

• Interested: GregTaylor

• Status: BrainDump

• Branch:
• Malone Bug:
• Packages:
• Depends:
• Dependents:

  FullSearch(HelpfulHelp)

• UduSessions: none

Summary

Ubuntu needs vast improvement in the quality, targeting, and presentation of its help and documentation ...

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 (but see CommandLineDisintegration).

For most people, their primary access to Ubuntu's help is a program with the unfortunate name "yelp" (a name that appears in the About box and various other places). 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, [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.

Most individual programs offer their own help, which is good; but it is usually accessed from a menu item labelled "Contents", which is non-obvious.

As for the help itself, it is largely 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 it 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 each use their own help viewer with its own interface design. 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.

How help should work

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

Random notes

• 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

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.

1. Write some general help for Ubuntu following the assumptions above (see [http://ubuntu.com/wiki/LocalHelp LocalHelp]).

2. A bounty to add search to yelp.

3. Rename yelp to HelpViewer or some other human-understandable name.

4. A bounty to get Gimp help displaying in HelpViewer.

5. Investigate feasibility of a print function.

Data preservation and migration

Packages Affected

• scrollkeeper
• ubuntu-docs
• yelp

Outstanding issues