Based on a survey which I carried out with nine technical writers last year and based on my own experience, I’d like to address three main issues in the Eclipse help system and suggest some ideas how to improve them.
Issue 1: Top-most search results irrelevant
More often than not help is entered via search than via navigating the table of content. In cases where the requested information is available but cannot be found, this is often not because of none or too few search results but because of too many. For example, in the search results for console, Clear Console and Pin Console are displayed above Console View.
Maybe the ranking could be improved (see bug 356623) by taking the TOC hierarchy (in the TOC both Clear Console and Pin Console are children of Console View) and the linkage into account. Currently the link text is attributed to the topic that contains the link instead of – like in Google – the target topic. Especially, topics that contain the search expression in the See also or Related topics sections only should not be found. Another idea would be to have a kind of auto-grouping function similar to Google’s “More results from…” feature or similar to the already existing “Show result categories” function which has to be enabled manually and which works only on the book level instead of any arbitrary depth.
Issue 2: Nothing found
Stemming is applied to the words of the query, e.g. trick finds tricks or restoring finds restore (tip: to disable stemming surround query with quotes) but if you search for Runing external tool then nothing will be found. One little typo (in the query or in the documentation) and the Search Results tab is empty; no Did you mean: Running… will assist you (see bug 356624).
Wildcards (e.g. th?se finds these and those, work* finds workspace and working sets) and the not yet by Eclipse Help supported fuzzy search (e.g. thus~ finds this) extends the result set too, but only few people use or would ever use it at all. Also according to the survey, the missing Did you mean feature would be much more preferred than the already supported wildcards and the not yet supported fuzzy search.
Issue 3: Sharing (Web Application only)
Sharing a link that refers to a specific topic of http://help.eclipse.org or of another Eclipse Help based web site, so-called deep linking, is tricky because even if you navigate to a topic the web site address remains the same. To bookmark a specific topic or to share a link to a specific topic you have to copy the link of this topic in the table of contents. This problem could be solved by rewriting the hash part of the address via JavaScript (rewriting the main part of the URL is forbidden for security reasons) like Orion does (see bug 315013).
Cent 2: Thanks!
All of the survey participants and I are very satisfied with the Eclipse help system – a special thanks to Chris Goldthorpe for quickly fixing two problems that occurred with our extremely large documentation. But as you know: give them an inch and they will take a mile and the best is the enemy of the good. 😉
Open Source does not require such warnings – doesn’t work anyway with pre-school children as I saw myself
eclipse howl 
