[maemo-developers] Proper documentation (was Re: [maemo-developers] HildonProgram input to gtk_widget_show()?)

[From: Aaron Levinson]

As can be seen at 
http://www.gossamer-threads.com/lists/maemo/developers/10038?search_string=HildonProgram;#10038 
, this isn't the first time this question has been posted to the list.  
Unfortunately, it appears that Steve's question went unanswered when he 
posted to the list in July, and soon after, he stopped posting to the list 
altogether.

As is often done in the developer documentation on maemo.org, the various
how-tos refer to the source for maemopad for more information.  As a
technique to shorten the amount of text that needs to be included in an
article, it works, but it tends to leave a lot of questions unanswered.  
There can be many things found in the source code that are not explained
in the relevant articles, and it can be unclear where to go to find
explanations.  However, in this case, the problem is compounded further,
because the source code example that is supposed to demonstrate how to
code a proper maemo application repeats the error.  One wonders if
maemopad was even built with the 2.0 SDK, let alone tested.

Also, passing in a HildonWindow * to gtk_widget_show() before calling
gtk_main() raises additional questions, because as stated in the
documentation, there may be multiple HildonWindows, and each window could
be added to the HildonProgram to provide a different view.  In the past,
when HildonApp was a GtkWidget, there was a single top-level widget that
was suitable for the call to gtk_widget_show().  This is no longer the
case, and it is unclear how to make things work if the developer were to
use multiple HildonWindows.

Last night, I found myself muddling through the "Making a Package for the
Application Manager" how-to.  It's not just that this how-to appears to,
unfortunately, be written for a semi-advanced audience that already has
experience creating packages.  It's simply difficult to follow this
how-to--there are lots of grammar issues, little contextual information,
and other issues.  For instance, it refers to various fields that may be
modified in the debian control file, but the control file is barely
mentioned.  It has a section about providing an icon in base64 format, but
there is no information for how to go about converting to base64.  It
suggests to go to the Debian Policy Manual, section 5.7, for more
information, but there is no link to the manual anywhere in this how-to,
and in addition, section 5.7 of the manual (once found by searching on the
Web) doesn't provide much useful information.

Without proper developer documentation, I don't think it is realistic to
expect many developers to migrate to the maemo platform.  Sure, maemo is
fine for experienced developers, who have likely already developed for
Linux/Unix, have some Gtk experience, etc.  But, there are Nokia 770 users
out there who have no or little Linux experience and may also be
developers.  I wonder how many developers have simply given up on maemo
because of documentation.

I hope something can be done to address the deficiencies in the developer
documentation.  Unlike on the wiki, this documentation cannot be easily
enhanced by the community, and submitting bugs against documentation in
Bugzilla is tedious.

Regards,
Aaron Levinson

On Wed, 29 Nov 2006, Johan Bilien wrote:

> Aaron Levinson wrote:
> 
> >In all the examples at maemo.org, I see the following:
> >
> >gtk_widget_show(GTK_WIDGET(program));
> >
> >program is of type HildonProgram *.
> >
> >It is unclear to me how this could ever work.  HildonProgram is not a 
> >GtkWidget.
> >
> >So, is this actually correct?  Do the documents on-line need to be changed 
> >to instead pass in a HildonWindow?
> >  
> >
> 
> Yes indeed,
> 
> I filled #889 against the documentation. It seems the documentation was 
> ported a bit too blindly from HildonApp to HildonProgram ...
> 
> Thanks,
> Johan.
>