Re: (Potential) Request for UI- and feature-freeze break for Yelp

[Shaun McCance <shaunm gnome org>]

On Thu, 2006-08-31 at 13:02 +1000, Jeff Waugh wrote:
> <quote who="Matthew Paul Thomas">
> 
> > Trying to stay away from the bikeshed, but: This function isn't for
> > searching forums in particular, it's for searching the Web-based help for
> > the distribution (help.ubuntu.com for Ubuntu, novell.com/support for Sled,
> > fedora.redhat.com/docs for Fedora, and so on). So including "forums" in
> > the URL is misleading.
> 
> Right, this specification was never made clear. An implementation was
> demanded (at very short notice!), without sufficient details for making the
> choices necessary for hosting an API. I have tried fairly hard to boil it
> down to something future-proof, but I can't do that without a decent spec of
> the problem (and no, I'm not willing to just whack any old thing up and see
> what breaks in future).
> 
> So: I need you guys to give me a solid spec on what the API will do, and
> where you see it going in future. Ideally on a wiki page or in a single
> email (rather than individual dribs and drabs). We should take creation of
> web APIs as seriously as we do platform APIs.

The purpose of this thing, as the user sees it, is to
find more information online whenever our documentation
just isn't doing its job (or our search isn't returning
good results).  The user searches for something in Yelp,
finds no good results, and decides to try his luck with
the intarweb.

Community forums are a natural place to go for help, but
vendors may have better ideas for their users, especially
for paying customers.

There are two reasons for having a central proxy script:
First, we can future-proof against other sites failing to
exist, or the addition of official (better?) forums; and
second, we can log the queries users make, independently
of wherever we ultimately send them.

Logging is not evil.  We have no intention of tracking the
users themselves.  We won't store usernames or IP addresses
or anything like that.  We just want to know what strings
get typed into search fields.  This can help us understand
what people are looking for in the documentation, which can
ultimately help us write better documentation.

We have actively considered the following additions:

1) Actually logging stuff. ;)
2) Sending the version of Yelp/Gnome.  This will allow us
   to see if changes to the documentation have actually
   had an impact.
3) Sending the user's language, potentially allowing us to
   redirect users to help sites in their native language,
   if suitable sites exist.
4) Allowing our distributors to direct their customers to
   their own support sites.  They could either bypass our
   script entirely by patching Yelp, or we could have Yelp
   include distro information, and make the redirect script
   acknowledge known distros.
5) Allowing documents themselves to specify a URL for web
   queries, which would be used with in-document search.
   This would have no effect on our server script.

That's the nutshell version of every conversation I've been
involved in regarding this.

--
Shaun