HelpfulHelp

Differences between revisions 12 and 13
⇤ ← Revision 12 as of 2005-06-16 02:44:01 →
Size: 13961
Editor: 203-167-186-66
Comment: condense, more links
← Revision 13 as of 2005-06-16 18:08:16 → ⇥
Size: 14357
Editor: 203-167-186-66
Comment: + help.ubuntu.com; more condensing; -> DraftSpec
Deletions are marked like this. Additions are marked like this.
Line 6: Line 6:
 * Contributors:
Line 8: Line 7:
 * Status: BrainDump  * Status: DraftSpec, JeffWaughQueue
Line 16: Line 15:
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. 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.
Line 20: Line 19:
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. 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.
Line 27: Line 26:
 * may not even have Internet access.  * may not have Internet access.
Line 30: Line 29:
 * 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		  * are accessing [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
 * are often frustrated, impatient, and pessimistic about the usefulness of the help
 * almost always want to [http://web.archive.org/web/20021213225158/http://world.std.com/~uieweb/online.htm 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
Line 37: Line 36:
 * will be most likely to succeed if they can read it while following the instructions in the program alongside  * will most likely use it successfully if they can read it while following the instructions in the program alongside
Line 42: Line 41:
 * 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.  * 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 the Ubuntu Help to find out how to get his dialup connection working.
Line 44: Line 43:
 * 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.  * 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.
Line 46: Line 45:
 * 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].  * 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 [http://httpd.apache.org/docs/howto/htaccess.html the apache.org page about .htaccess].
Line 48: Line 47:
 * 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.  * 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.
Line 54: Line 53:
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. 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.
Line 56: Line 55:
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. 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://www.google.com/search?q=cache:Ab7nx7LLa3EJ:www.infomanagementcenter.com/enewsletter/200411/secondary.htm+%22even+fairly+sophisticated+users+were+clicking+the+graphic%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.
Line 58: Line 57:
Firefox, Gimp, and Open''''''Office use their own help viewers with inconsistent interface designs. The [http://www.mozilla.org/projects/help-viewer/ Firefox] and Open''''''Office 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. Firefox, Open''''''Office, and Gimp use their own help viewers with inconsistent interface designs. The [http://www.mozilla.org/projects/help-viewer/ Firefox] and Open''''''Office 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.
Line 68: Line 67:
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. 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 [http://tc.eserver.org/10347.html 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 [http://klariti.com/technical-writing/Improve-Usability-Embedded-Help.shtml embedded help] in dialogs and rarely-used windows.
Line 72: Line 71:
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 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, a less fragile alternative to linking to individual pages.
Line 78: Line 77:
 * [http://www.xvsxp.com/help/ Comparison of help viewers in Windows XP and Mac OS X]
Line 85: Line 85:
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. 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.
Line 87: Line 87:
 * 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).  * A distinct but unobtrusive link at the bottom for "Look for more help online" should be present at the bottom of all search results, and at the bottom of all pages except pages that explicitly opt out. This link should open a Web browser to search help.ubuntu.com for pages containing the search terms if there are any, or the title of the current page otherwise. 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).
Line 89: Line 89:
 * 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.  * 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:''
 * [http://www.helpware.net/longhorn/review1b.htm#No_Dead_Ends Windows Longhorn's "Assistance Escalation Path"]
Line 93: Line 96:
After asking any nearby humans, many people will search the Web rather than venturing into a program's Help menu. 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, this may even produce better results, because the Web as a whole uses synonyms and misspellings more thoroughly than the help does.
Line 95: Line 98:
The most useful troubleshooting techniques are generally to ask a knowledgeable person or group, or to ask Google. 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 [https://wiki.ubuntu.com/RestrictedFormats RestrictedFormats]), while the packaged help should have a slight bias towards information on how to connect to the Internet or use programs offline.
Line 97: Line 100:
* 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. Like the packaged help, online help should be [http://www.useit.com/alertbox/9710a.html 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.
Line 99: Line 102:
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, 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.
Line 105: Line 104:
Like the packaged help, online help should be task-centered, though there is more scope for tutorials and overview documents.

...
Line 110: Line 105:
 * [http://codex.wordpress.org/Main_Page WordPress Codex]
Line 111: Line 107:
 * [http://en.wikipedia.org/wiki/Wikipedia:Multilingual_coordination Wikipedia: Multilingual coordination]
Line 114: Line 111:
=== 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.''		 === Suggested Breezy goals ===
Line 119: Line 114:
 1. Write general help for Ubuntu following the assumptions above (''see'' [https://wiki.ubuntu.com/LocalHelp LocalHelp]), and have this help appear immediately when the "Help" menu item is chosen.  1. Write general Ubuntu Help following the guidelines above (''see'' [https://wiki.ubuntu.com/LocalHelp LocalHelp]), and tweak yelp so that it opens to Ubuntu Help rather than the current hierarchy of books.
Line 123: Line 118:
 1. Rename yelp to Help''''''Viewer or some similarly human-understandable name.
Line 124: Line 120:
 1. Rename yelp to Help''''''Viewer or some similar human-understandable name.
Line 126: Line 121:
== Future work == === Future work ===
Line 129: Line 124:
 * Provide the ability for distributors to add a support link to the bottom of every set of search results and every help page except the front page.
 * Hide or remove the table of contents frame (and the previous/next links) from the help viewer, making the default window size smaller to match.		  * Implement the opt-out supplemental links for help pages as described [#head-51bc9985ea7d99f0ecfb85c2a04bd70968dc7aca above]. As a useful example for distributors, link to a context-sensitive search of help.ubuntu.com from all pages except the front page, the "Getting more help" page, and the pages about connecting to the Internet.
 * Hide or remove the table of contents frame and the previous/next links from the help viewer, making the default window size smaller to match.

Making Ubuntu Help helpful

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.

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 [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

  • are often frustrated, impatient, and pessimistic about the usefulness of the help

  • almost always want to [http://web.archive.org/web/20021213225158/http://world.std.com/~uieweb/online.htm 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 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, Niels 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. 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 [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 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://www.google.com/search?q=cache:Ab7nx7LLa3EJ:www.infomanagementcenter.com/enewsletter/200411/secondary.htm+%22even+fairly+sophisticated+users+were+clicking+the+graphic%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, OpenOffice, and Gimp 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. 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.

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 [http://tc.eserver.org/10347.html 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 [http://klariti.com/technical-writing/Improve-Usability-Embedded-Help.shtml 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 grouped underneath results from the current program's help. 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.

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.

  • A distinct but unobtrusive link at the bottom for "Look for more help online" should be present at the bottom of all search results, and at the bottom of all pages except pages that explicitly opt out. This link should open a Web browser to search help.ubuntu.com for pages containing the search terms if there are any, or the title of the current page otherwise. 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:

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, this may even produce better results, because the Web as a whole uses 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 [https://wiki.ubuntu.com/RestrictedFormats 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 [http://www.useit.com/alertbox/9710a.html 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.

Comparisons:

Implementation

Suggested Breezy goals

In approximate order of importance:

  1. Write general Ubuntu Help following the guidelines above (see [https://wiki.ubuntu.com/LocalHelp LocalHelp]), and tweak yelp so that it opens to Ubuntu Help rather than the current hierarchy of books.

  2. Write a one-page installation guide for Ubuntu.
  3. Add a search function to yelp.
  4. Add a print function too.

  5. Rename yelp to HelpViewer or some similarly human-understandable name.

  6. Set up help.ubuntu.com as a repository for reviewed versions of documents on wiki.ubuntu.com, with an easy approval process.

Future work

In approximate order of importance:

  • Implement the opt-out supplemental links for help pages as described [#head-51bc9985ea7d99f0ecfb85c2a04bd70968dc7aca above]. As a useful example for distributors, link to a context-sensitive search of help.ubuntu.com from all pages except the front page, the "Getting more help" page, and the pages about connecting to the Internet.
  • Hide or remove the table of contents frame and the previous/next links from the help viewer, making the default window size smaller to match.

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

  • Add index-based spelling suggestions to the search function.

  • Get OpenOffice to use the standard help viewer.

  • Get Gimp to use the standard help viewer.
  • Get Firefox to use the standard help viewer.
  • Implement highlighting of controls (requires XOrg Composite + Damage).

  • Begin writing useful help for programs in main and push it upstream.

See also

HelpfulHelp (last edited 2008-08-06 16:16:34 by localhost)