Why help writing for Maemo applications sucks?

Why help writing for Maemo applications sucks?

We like good applications. We can spend a lot of time telling our friends about fantastic applications we met. But application will be more better if one small thing can be improved.

Beside a cool functionality, a program must have well-designed User Interface (UI).

Good UI can help users not to get lost in the set of buttons and checkboxes, can help to do his task more efficiently and more quickly, and make all work with application intuitive. Despite on GUI is a key to success, it is not everything: even the world's better UI cannot tell the user about all allowable tricks and hints. The solution is: to write a documentation or/and write quick help available from the main menu. I suppose lot of users firstly looks to help to find answer to the question, and then, if nothing, go to the documentation/google. So, this is why having application help is a so important case.

Maemo applications don't differ lot from desktop applications. But why help writing for Maemo applications sucks? I suppose that not only I ran into the following problems when I firstly
met Maemo help subsystem when started writing help for Conler.

1. Awful OSSO Help format description

(for who not familiar with the idea: help system in Maemo is implemented using OSSO Help framework. This framework requires that all help files must conform to the special XML-based format).

When you were reading Maemo_*_Reference_Manual_for_maemo_*.pdf you surely had read a section dedicated to the help writing. It is very "comprehensive", is not it? It has a list of available elements and short descriptions for them, some examples, and nothing more. What is the hierarchy of the elements? When I should use "element-1" and when I don't have to use "element-2"? Unfortunately answers to these questions can be found only in researching already written help files located in /usr/share/osso-help.

2. No abilities to validate written help.

The good practice in working with XML files is when it is done, the result must be checked for correctness. It can be done using XML Schema, DTD, or RelaxNG, whatever. But there is no schema files for our case!

The only way to check that the help will be shown correctly is:

1. Make XML non-schema validation, using, for example, 'xmllint': we will be sure that the document conforms to XML.
2. Try to browse it in Maemo: if it is shown as expected, the work can be supposed done.

I really was trying to find such files. But I did not manage: because they ain't exist, even on the framework's homepage.

3. No good tool/solution for non-technical people to write help documentation.

Help for applications might be written by non-technical people, not developers only. But how can they do it if they even don't have any idea how to do this -- this is a result because of points 1 and 2 above.

The usual steps for novice to write a help:

1. Read Maemo_*_Reference_Manual_for_maemo_*.pdf
2. Try to find more information
3. Research files in /usr/share/osso-help to get real-life examples
4. Write a first version of the document using simple constructions only
5. Validate it
6. Improve document using more advanced constructions
7. Deploy to the application package.

Too complicated, is not it? Have to say that I did these steps too when I first was writing help for Conler. The next iteration of the process might be short. But it could be:

1. Read intro about writing OSSO help documents
2. Run editor and write following the tips about document structure. And not being worried about its correctness.
3. Deploy newly created help to the application package.

There is an obvious profit: if there were such a good tool/solution, non-technical people could be involved to Maemo development.

Lot of criticism without nothing useful? Actually not at all. Important step in problem solving -- is to find and describe it. Hope, being inspired by this text and having some experience in XML, I to release soon my implemented vision of the solution.