Searching the Documentation

[Phil Bull]

Hi guys,

I've been getting a bit of feedback about the documentation from a few
people recently, and it seems that a serious problem for them is
actually finding relevant documentation.

For example, there was a chap asking for documentation on using the
Terminal. We have plenty of this documentation on the Help wiki, but he
couldn't find it. When he got to it, it was exactly what he wanted.

I thought I'd provide an overview of the current state of searching our
docs, and suggest some possible improvements for discussion.


CURRENT SEARCH FACILITIES

The system docs are searched using Yelp's search. Unless Beagle is
installed, the results tend to be quite poor (two-word extracts,
irrelevant results etc), and the search is slow. There are bugs with the
Beagle-enabled search too. I don't know if this is any better on KDE.

The system docs as published online [1] have no direct search function.
They seem to rarely turn up in Google results.

The community documentation wiki [2] has a search function which can
search either 'Titles' or 'Text', which is a pointless distinction from
a user's point of view. The Title search results have no page extracts
or summary of what the page is about, so you have to go from the
SometimesDifficultToReadWikiTitle. The Text search results are better,
but often include wiki markup in the extract they show, which is just
weird. Both searches are fast, however.

The forum [3] has a fast search, but doesn't have page extracts. The
basic topics are often lost in a sea of more advanced topics.


SUGGESTED IMPROVEMENTS

Ideally, we would unify the way we search the documentation, rather than
making users visit a load of different websites and making a load of
different searches. This would probably be difficult to do in the case
of the (offline) system documentation, but should be easy enough with
the others.

Google offer a service called Custom Search Engine [4] which would be
able to search all of our documentation at once. We could also integrate
it into the documentation websites and give it Ubuntu branding. There is
also the possibility of weighting and categorising search results.

Results could be weighted on the basis of which source they come from
(e.g. 4 for official docs, 3 for community docs, 2 for the forums and 1
for external docs), although I don't know if this approach would serve
users the best.

Does anyone have any thoughts on this?

Thanks,

Phil

[1] - https://help.ubuntu.com/
[2] - https://help.ubuntu.com/community/
[3] - http://ubuntuforums.org/
[4] - http://google.com/coop/cse/overview

-- 
Phil Bull
http://www.launchpad.net/people/philbull