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

Brainstorm link:

https://maemo.org/community/brainsto...ion_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.

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

Hear hear!

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

Luis, could you break the Brainstorm into a Problem + Solution format? Thanks.

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

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, this thread would essentially amount to a solution.

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

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.

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

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/

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

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.

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

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.

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.

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

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

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

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.

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

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.

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

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

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.