What's going on here?

Yelp has recently gained the ability to retry a search on a Web site. At the end of search results appears a link, "Repeat the search online at GNOME Support Forums". The text and target of this link can be customized easily by a distributor: for example, it might search help.ubuntu.com in Ubuntu, novell.com/support in Sled, or fedora.redhat.com/docs in Fedora. (The default is gnomesupport.org/forums only because Gnome has no help site or knowledge base of its own.)

The function is implemented in yelp-search-pager.c. More details in bug 344843.

What's needed on gnome.org?

A stable, never-breaking URL schema for these searches, that redirects to searching the Gnome support forums. Something like: http://api.gnome.org/help?q=can't+log+out

The URL needn't mention forums, because the function is about help in general, not forums in particular. And it needn't mention yelp, because it might also be used by some other help viewer (for example, a mini help viewer integrated into a program's window).


There are several reasons to make it easy for people to jump from a local search to a Web search when looking for help.

  • Online help can continue to be updated after the shipped help has been frozen. (For example, online help can describe workarounds for bugs that were recently discovered and won't be fixed in the current version of the OS.)

  • Online help searches can be logged and analyzed, to improve (a) Gnome itself, (b) Gnome's help, (c) Yelp's search function, (d) the distributor's online help, and (e) the distributor's online help search function.

  • Online help is often more extensive than local help, because there is more space on a Web site than on a CD (or set of CDs), and there are usually more authors for a wiki than for DocBook documents.

  • Jumping onto the Web is something people often do anyway, sometimes without even checking the local help first. Making it easy for people to jump from one to the other will make them (a bit) more likely to try both.

  • More generally, this link is one step on an escalation path (eh?) from concise help in a program's interface, to its local help pages, to help on the Web, to community or paid support.

Possible future changes

  • Once we have topic-based help (see ProjectMallard) where a page knows what program it's providing help on (if any), it may be appropriate to add a &program= parameter to the URL to return program-specific results. (So for example, searching for "can't connect" will return different results depending on whether you're searching Epiphany help or Evolution help.)

Distributors are likely to add other parameters to the search, so it ends up something like http://help.example.com/search?q=can't+log+out&lang=en&version=2007. But because of the way the feature is implemented, these parameters don't need to be standardized or implemented at gnome.org.

Attic/SearchingOnlineHelp (last edited 2013-12-03 22:52:55 by WilliamJonMcCann)