The most effective help is individual instructions and examples, one or two sentences each, integrated directly into the interface it is providing help on. Upstreams whose software is included in Ubuntu (especially the less-often used ones) should be encouraged to add such hints, through a section in the HIG and friendly evangelism on mailing lists etc.


People other than programmers are highly reluctant to use anything in the Help menu. The most useful help is tips and and hints embedded in the software itself, especially in dialogs and rarely-used windows.

Use cases

  • Sally is trying to log in to her GNOME desktop using a different language. She clicks "Language" on the GDM screen, and wonders why Chinese is not listed, and then how she can make her computer support Chinese.
  • Lu sees the "Sessions" item in the Preferences menu, and wonders what it's for. He's not quite interested enough to look in the separate help, though. So he closes it and never looks at it again, missing out on the time he would have saved by adding Evolution to his Startup Programs.


  • All software in GNOME.
  • All software in main (including OpenOffice.org, Firefox, and Thunderbird).


Current examples of embedded help:

  • The blurb at the bottom of the Language Selector (cf. GdmRoadmap).


Since this approach is distributed across dozens of upstream projects, it should be implemented as a section in the GNOME HIG, then evangelized to individual projects.

Outstanding issues


EmbeddedHelp (last edited 2008-08-06 16:32:01 by localhost)