A Lens would be a useful interface to make help on Ubuntu easier to access. Currently, there is a lens that searches, but we could do more.

Short Statement of Goal

Help with the use of and problems with Ubuntu can sometimes be difficult to find. While well written documentation does exist, it can be difficult for the novice to find where it is. Additionally, users often have to search the internet for solutions to their problems and may be unaware of the best places to find solutions.

We should adapt the AskUbuntu lens to be an easily found starting point for finding help about how to use Ubuntu and how to solve problems with it. Ideally, provide multiple help sources aimed at both the novice and advanced user.


The AskUbuntu lens is an excellent way to find answers to problems users might have with their systems. It searches, a community maintained website containing all manner of questions and answers relating to Ubuntu. Users can be generally confident that information found there is reliable and since it is continually updated, incorrect information is usually quickly corrected.

The help lens would take this one step further, by also leveraging help documentation on the user's own system as well as other sources determined to be trustworthy and useful.

Your feedback on anything here is welcome at the bottom of this page.


There are currectly 3 sources that I can think of that would be suitable for this lens:

  1. Results from Ubuntu's internal help, Yelp
  2. Results from
  3. Manpages

A search could provide results from all or any of these sources. Separate scopes should be provided for each source so that users can add or remove any external search sources they wish to, although, results from Yelp should always be available.

Lens Appearance

Currently, in Precise, the AskUbuntu lens looks like this:

AskUbuntu Lens Precise Screenshot

The current proposed Quantal version of the Help Lens looks like this (Note: The icons in this image have a black background due to a bug in Unity):

AskUbuntu Lens Proposed Quantal Screenshot

The following features are visible here:

  1. How to find help gets top priority (Ask on AskUbuntu, search on AskUbuntu)

  2. Yelp results get top priority of the search results. These are official documentation and as such are highly trustworthy
  3. AskUbuntu answered questions get second priority

  4. AskUbuntu unanswered questions get third priority

  5. Manpages get lowest priority of search results
  6. Tags from AskUbuntu (not visible in thescreenshot) get lowest priority of all

Additionally, Yelp results get icons based on the program to which the help belongs. eg. Empathy help gets an empathy logo, Ubuntu documentation gets an Ubuntu logo. AskUbuntu results containing a tag which matches a program icon on the user's system also get that icon.



There are 3 proposed sources here: Yelp, AskUbuntu and Manpages. Are these suitable? Are there other sources that should be considered?


The Yelp source will provide results in the user's system language (assuming the documentation is available in that language, of course) is only available in English. Should those results be available to non-engish speakers? Should they be directed to machine translated versions of the results? Manpages are only available in English, but if you're advanced enough to need to use manpages, this is probably not a major issue.

Programming Language

The lens is currently written in Python. Is this acceptable? Are there compelling reasons to rewrite it in Vala, for example?


The icons should look good. The ones in the Precise lens don't convey too well what they represent. The ones in the proposed Quantal version are very orange (especially if you have a screen full of them). The lens icon could be better as well. Obviously the askubuntu logo would no longer be appropriate and the question-mark-in-a-circle follows the lens categories motif a bit too closely. Any other ideas which would convey 'help'? Should AskUbuntu results or Yelp results show an application icon if they're related to a specific application?


What filters, if any, should be present? Currently, filters exist to search different stackexchange sites. Should these be present? There are also search shortcuts available to search stackexchange. If the visible filters were removed, should the search shortcuts be also, or left as an easter egg style feature?


The main package should be called unity-lens-help and contain the lens base and the Yelp scope. The askubuntu scope should be moved to unity-scope-askubuntu. The manpages scope should be created as unity-scope-manpages.

Install By Default?

That would be nice. If it were to be, unity-lens-help and unity-scope-askubuntu should be installed by default, but unity-scope-manpages should not. Manpages are scary and confusing for the novice user. Advanced users should be well able to install the scope if they wish.

AskUbuntu Backend

Stackexchange (who run askubuntu) impose per-application rate limits on API queries. How do we get around them if many people are using the lens at once. Currently, there are a couple of servers set up that mirror the questions on askubuntu. Can that be scaled up if needed?

Any Other Issues?


Your comments on the design of the Help Lens are welcome here. Please comment at the bottom of the page, and sign your name with each comment. Create a subpage for long suggestions. Thanks!

HelpLens (last edited 2012-05-28 10:33:39 by markjtully)