Implement a search-able, on-line help and documentation framework

Posted on 2009-12-28 16:03 UTC by Luis Soeiro. Status: Under consideration, Categories: User Experience.

There is one thing about MAEMO 5 that seems to be a really missing: there is no context help whatsoever on the device. Nor there is any hope for improvements because there is no official framework or directive regarding device or application documentation and help.

I think I remember reading somewhere that the lack of a help framework was a "feature" and not a bug. I would like to suggest otherwise.

It would improve the usability to have a common maemo-wide framework for providing context and user-documentation.

Hera are some issues caused by not having any help and documentation system on the N900 device:

1) There are several instances when the user has no clue as to what the currently displayed options are for or how to use them. Usually, he or she must use a trial-and-error approach. It would be much better if there was a mechanism to display some hints, tool-tips or help pages about the available controls in that view.

2) There is no central location where the user can search for some topic in order to find out how to perform an activity. To make things more difficult, sometimes the desired option is just hidden from view (a button that is not in the viewable area). Examples of such activities would be: "How to change a ring tone; How to edit a profile; How to connect to a computer using bluetooth."

Brainstorm discussion:

Thanks for your attention


Solutions for this brainstorm


Solution #1: Clone KDE's help system

Posted on 2009-12-28 17:19 UTC by Luis Soeiro.

We could at least borrow from the QT/KDE documentation framework. A bunch of HTML files, indexable, fire-able either from within the application or by an external information applet.

Since QT already supports Maemo 5 and that Maemo 6 is supposed to be all QT-based, it seems logical to just clone the KDE help system.

It would also bring the benefit of making it easier to port existing KDE-aware applications to Maemo 5 (and others).

Here is a link to help understando how it works (on KDE):

Kde Help System User Manual []


Solution #2: Workaround using html

Posted on 2010-01-05 16:07 UTC by Luis Soeiro.

I think that a more integrated approach (like the KDE solution) would be better than this one, but having nothing is the worst case scenario. So I propose a workaround:

Each application could provide HTML pages such as the following:

  1. index.html.  This is the entry page that must contain a description (however short) of the application and links to other pages.
  2. For each dialog or screen that the users sees there must be a html page describing the available options, fields, controls and so on. All pages also point to the entry page.
  3. For each dialog, screen, etc, there is a ? (question mark icon - the help button) that launches the N900 browser on the current html page. It can alternatively just launch a html component that shows that page.
  4. Finally, there could be a system software that could index all html pages and build a search-able page that could be directly queried by the user, whenever he or she taps on the "Help application" (a question mark icon at the applications menu). Each time an application is added or removed from the system, the index database can be rebuilt.
  5. As for CLI software, instead of stripping the docs, we could just optify the location for the man pages. And add the man command to the installed applications.

Solution #3: Provide a help wiki and export to the device

Posted on 2010-01-08 13:12 UTC by Luis Soeiro.

Based on the discussions on the thread, here is a new approach that may be easier to implement and to get more collaboration from the community:

1) Make a Wiki repository that is very easy to edit, even for non developers. Do it with standard naming conventions for pages, titles, folders, etc, depending on the name of the related package.

2) Export desired parts of the Wiki as static, navigable, HTML pages and place that on a standard location on the N900 device. That way, if the user clicks on a help icon on the application, the local browser is fired on that page. No Internet connection required.

3) Develop a Maemo 5 application that searchs for installed packages and fetches all the related wiki pages to the device. The application can keep the installed help pages uptodated, depending on the current version of the installed applications.

4) There could even be a link on the device itself that navigates to the help wiki, in order for the user to fix, edit or add something. This requires an Internet connection.


This approach has some advantages:

  • It may get the community to contribute to the help system, even if they are not developers. There are many people willing to help.
  • It uses the same source documentation to have an off-line copy at the device. This will improve the system usability a lot, since everybody will have the documentation at all times.
  • Since the wiki is viewed as standard html for any browser, it might be easy to retrieve and convert the wiki as standrad html files. This would not increase the memmory footprint on the device (a wiki system would not be required).

Solution #4: Use existing resources

Posted on 2010-01-08 13:22 UTC by Andraž Levstik.

Have a system that can pull in man pages and other such things, maybe even web sites etc...

Latest activities to brainstorm Implement a search-able, on-line help and documentation framework