PDA

View Full Version : Implement a search-able, on-line help and documentation framework for Maemo 5


soeiro
2009-12-28, 15:49
Brainstorm link:

https://maemo.org/community/brainstorm/view/implement_a_search-able-on-line_help_and_documentation_framework/

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.

Here 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."

Thanks for your attention

Luis
-----------
Here is a possible solution (its already in the brainstorm):

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.

Viipottaja
2009-12-28, 16:12
Hear hear!

Texrat
2009-12-29, 03:46
Luis, could you break the Brainstorm into a Problem + Solution format? Thanks.

ARJWright
2009-12-29, 06:27
This thread illustrates two issues, one in that the forum needs to be reorged, two in that the logic used to display similar topics when new threads are created needs to be tweaked...

...for the latter, this idea was posted already (http://talk.maemo.org/showthread.php?t=34922), this thread would essentially amount to a solution.

soeiro
2009-12-29, 16:38
Luis, could you break the Brainstorm into a Problem + Solution format? Thanks.

Well, I thought I had actually done that the first time. Take a look now and see if it is better:

Problem: lack of context and search-able user help on the device.
One suggested solution: clone the KDE help system.

Jaffa
2009-12-29, 16:58
Some background: there was a help framework in Maemo <=4 which was rarely used by third party applications and rarely used by users. That's why it was dropped from Maemo 5 (AFAICT).

I've even just found out there was a WYSIWYGish editor for it: http://thekondor.net/osso-help-plugin/

soeiro
2009-12-30, 13:06
Some background: there was a help framework in Maemo <=4 which was rarely used by third party applications and rarely used by users. That's why it was dropped from Maemo 5 (AFAICT).


It is interesting, but IMHO it doesn't seem to be a good excuse. At least the base system should have been very well documented! If 3rd party applications don't follow the rules, too bad for them...

For instance. The current trend in not providing any documentation at all looks just like an attempt to go back to DOS 2.X and DOS 3.X days. At that time you could do NOTHING in the OS without having the huge bible that was the DOS Manual. No quick way to fix something for a friend or a work colleague.

People are going to the extreme measure of stripping of existing documentation files to reduce application sizes. What good is a piece of software if you don't know how to use it?

While using the GUI applications are becoming even more difficult because of lack of help systems (and there is a lot of problems of figuring out how to map ported application keys to the N900 keyboard) the situation is really critical in the command line front. It is the worse experience that I can remember. There is no MAN or INFO tools. Executables refuse to show help even for the basic commands (for example "foo --help" shows "usage: foo").

I can understand that having help files in all earth existing locales can bring some bloat to the table, but not having anything at all is much worse.

Jaffa
2009-12-30, 13:19
It is interesting, but IMHO it doesn't seem to be a good excuse. At least the base system should have been very well documented! If 3rd party applications don't follow the rules, too bad for them...

However, if usability tests found that the base system could be operated without users using (or possibly even being aware of) a help system; spending the resource to develop and maintain the framework and the documentation is a hard decision for Nokia to take.

Certainly, on the N900 the over-simplification of the UI means there's nothing I've even referred to the manual for (I've not even opened it). I never looked at the help on a 770, N800 or N810 either; and my wife's never looked at it on her N810 AFAICT.

For instance. The current trend in not providing any documentation at all looks just like an attempt to go back to DOS 2.X and DOS 3.X days. At that time you could do NOTHING in the OS without having the huge bible that was the DOS Manual.

I think the rationale (and there's a thread about it on maemo-developers when the first Fremantle SDK alpha was released without osso-help) would be that the system and its applications should be so simple to use that providing an online help framework on the device is unnecessary. Complex applications can link to online help if they wish.

[T]he situation is really critical in the command line front. It is the worse experience that I can remember. There is no MAN or INFO tools. Executables refuse to show help even for the basic commands (for example "foo --help" shows "usage: foo").

Indeed, an unfortunate side-effect of Busybox being very lighweight. But, the command line doesn't lend itself to experimentation on the device; and man pages are a separate issue to GUI app help frameworks (although you could argue [incorrectly, IMHO], that the absence of both is symptomatic of the same underlying assumption).

I can understand that having help files in all earth existing locales can bring some bloat to the table, but not having anything at all is much worse.

Well, depends how quickly you want your rootfs to fill up (before the problem goes away in Harmattan)

soeiro
2009-12-31, 18:16
However, if usability tests found that the base system could be operated without users using (or possibly even being aware of) a help system; spending the resource to develop and maintain the framework and the documentation is a hard decision for Nokia to take.

Here I don't agree. Documentation is part of the effort, not something optional and extra. I'm not saying "write down full length volumes of books". Just document what the software does and what the options are for, at least.

If a company thinks it can save some bucks by dumping the documentation efforts it should really get a new management team. Every time a user doesn't understand how to do a simple thing he or she may have to call for support, or to complain. That can cost a lot more.


Certainly, on the N900 the over-simplification of the UI means there's nothing I've even referred to the manual for (I've not even opened it). I never looked at the help on a 770, N800 or N810 either; and my wife's never looked at it on her N810 AFAICT.


My experience was very much the opposite. I had to google for most of the things I would like to do. I've read the manual too, to make sure I didn't miss anything. I don't remember every problem that I have because of lack of documentation, but I can list some:


I couldn't figure out how to change a ringtone
I couldn't figure out how to reset the data plan counting
I didn't notice that the settings->Profiles screen had more button below "General" and because of that I couldn't access a lot of options
I couldn't change system sounds for taping
I'm still searching for a way to use the operator's SIM menu.
I still don't know how to use two dictionaries, how to change them and where those settings are expected to work. I don't know whether the hard of soft keyboard would be affected...
"Insert space after word" is kind of vague. insert spaces when, where? What key should I press to avoid autocompletion? What key should I hit to accept auto completion?
Where could I find the ESC key, TAB key, pipe key? How to select composite characters, such as ã ó í é, etc
What is "Nokia messaging"? Is it included, free, paid for?
Will the phone download all my emails? How to tell it not too, because of high data cost?


This list continues... Most issues, if not all, could have easily being avoided if there was some lines of text available to describe what was the purpose of buttons and options.


I think the rationale (and there's a thread about it on maemo-developers when the first Fremantle SDK alpha was released without osso-help) would be that the system and its applications should be so simple to use that providing an online help framework on the device is unnecessary. Complex applications can link to online help if they wish.


I agree with the target of making a system as easy as use as possible. But that includes hinting the user on everything possible to make him or her accomplish a given task. I do find the Maemo 5 interface very dumbed down, but I'm used to playing with a lot of settings (KDE) and maybe that is why I expected to see a lot more options. it is a shame that nobody used "osso-help". But was it the developers fault or the framework? A good idea would be to reuse something that is readily available (KDE help system, HTML templates for help, etc).

I think that linking to online help content is not a good idea. For instance: what if you are trying to figure out how to connect? What if you are in a place or situation where there is no connection? What if the cost is too high?

That's why I think a good base framework would improve things. At least the base system (Nokia provided software) would use it and that alone would make the experience better than now. Good third party application developers wouldn't be offended if it was easy to add a few lines of descriptive text or html from a template.



Indeed, an unfortunate side-effect of Busybox being very lighweight. But, the command line doesn't lend itself to experimentation on the device; and man pages are a separate issue to GUI app help frameworks (although you could argue [incorrectly, IMHO], that the absence of both is symptomatic of the same underlying assumption).


Yes, I see that for CLI stuff "busybox" would be the one to blame.
Certainly GUI and non-GUI are different issues, but both deserve some consideration (even if for different solutions).

But what I fail to understand is that we are not talking about a 1MB, 64MB or 256MB device anymore. We have a 32GB device which could hold basic documentation for everything, including, let's say, basic English man pages without hurting too much the available free space.


Well, depends how quickly you want your rootfs to fill up (before the problem goes away in Harmattan)

We should make a list of all the problems that are blamed on the current partitioning scheme to help convince/aid in deciding for a better one... ;-)

soeiro
2010-01-05, 15:50
Hello

I see more posts of people puzzled by the N900 software in one way or other.

How could we get some support for:

1) Revert the current practice of "stripping the existing docs" to maybe changing where is is stored (/opt/something, if the internal flash issue issue is not sorted out yet)

2) Provide a default set of directories and framework for storing help files. I would suggest the most simple approach: creating help pages as html pages, one for each "dialog" that the user sees. Linking them in some standr way and placing them in a standard place. The application then can just fire the browser on the local file if help is called for.

benny1967
2010-01-05, 15:57
What I'm wondering is:

Would it be possible to simply (oh how I love this word...) take the code that forms the help framework in the good old pre-Fremantle versions, re-compile it for Maemo 5, upload it to Extras as libmhelp or such and thereby make it available for each and every developer who wants a context sensitive help system for his application? Or wasn't the code open?

mve
2010-01-05, 18:45
What about using wiki to make documentation for the software which needs it? I made http://wiki.maemo.org/Geocaching page some time ago to help geocachers with gpxview and maemo mapper.

Then we as a community would just need to make page for each program in wiki and write the documentation. Developers then could add link in their software to that wiki page. I actually tried to start that with http://wiki.maemo.org/OMWeather but I haven't had enough time to do it yet.

slender
2010-01-05, 18:59
mve,
I tought about that too. Maybe there shouldd be some sort of naming standardisation for example /manuals/desktop/conky.

Also it would be good that if in app manager links and email would be clickable or at least they could be copied to clipboard. Would make bug reporting emailing and reading manual easier and faster.

sjgadsby
2010-01-05, 19:24
Would it be possible to simply (oh how I love this word...) take the code that forms the help framework in the good old pre-Fremantle versions...

As far as I know, osso-help-ui was closed. I'm not sure if there were pieces of the OSSO Help Framework below the UI that were open.

Additionally, I've been told by developers that the OSSO Help file format was cryptic, barely documented, and difficult to work with. If the community is keen on developing a common help framework for interested Maemo developers to use, it might be best just to start anew with DocBook.

pycage
2010-01-05, 19:35
Wasn't the OSSO help system based on docbook, just like yelp on GNOME?

slender
2010-01-05, 21:44
Solutions you have provided sound good, but I have little doubt that they might be too complex/hard to edit for some users. I do not know how they integrate with this maemo.org system.

How easily they can be edited when compared to maemo wiki? They sound really good, but if people are not really motivated to write manuals and it´s work that can be done only by few people who probably have better things to do then i think writing manuals should be made really easy eventhought it might come with cost of some other aspect. There is already some people asking what they can do for community and they have zero experience on coding and devel-testing might be to complex or risky for them so writing manuals could be really rewarding. Editing community provided default wiki template is on my scale quite easy.

soeiro
2010-01-08, 12:57
Solutions you have provided sound good, but I have little doubt that they might be too complex/hard to edit for some users. (...)

(...) Editing community provided default wiki template is on my scale quite easy.

I agree with that, but that doesn't solve the "I'm off line and I don't know how to use this" problem. Therefore, I would like to propose a development of the wiki idea:

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).

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.

3) One can even create a Maemo application that searchs for installed packages and fetches all the related wiki pages to the device.

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

Please, go to the first post and vote for the brainstorm and the solutions...

ARJWright
2010-01-08, 13:05
I agree with that, but that doesn't solve the "I'm off line and I don't know how to use this" problem. Therefore, I would like to propose a development of the wiki idea:

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).

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.

3) One can even create a Maemo application that searchs for installed packages and fetches all the related wiki pages to the device.

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

Please, go to the first post and vote for the brainstorm and the solutions...

Ahem...
http://talk.maemo.org/showthread.php?t=34922

soeiro
2010-01-08, 14:54
Ahem...
http://talk.maemo.org/showthread.php?t=34922

Yeah... I've added a link to this thread from the other, too. Maybe we can merge all efforts...

Let's try to rearrange the main ideas:

Summary of ideas:


Reusing previous maemo help framework and API;
Cloning the KDE help system;
Using a well structured help Wiki in maemo.org and adding some kind of mechanism for synchronization with the device, for off-line reading.


Goals:


It has to be easy to implement - minimum effort for existing applications and developers;
It has to be easy to use for consulting, for a regular user;
It has to be easy to use for contributing, for developers and end users who would like to help;
It has to provide an off-line mode for the device;
It has to provide an easy mechanism of importing existing documentation (html pages, man pages, and so on);


Issues:

Developers might not want to use it;
An existing application might already have a (different) help system;
Not many developers are good at or like to write documentation

bbns
2010-01-08, 15:04
Maybe you guys looking for something like this?
http://library.forum.nokia.com/

But yeah, I know ... Maemo is missing there.

soeiro
2010-01-09, 18:59
Maybe you guys looking for something like this?
http://library.forum.nokia.com/

But yeah, I know ... Maemo is missing there.

I wouldn't say like that, since that library seems to be focused on development. As an idea, it could work.

On the other hand, I'm favoring a wiki-like solution for gathering and viewing documentation on maemo.org and html viewing for displaying it on the device.