[maemo-developers] Support to non-Linux developers (was Re: GeneralMaemo/Scratchbox/N800 help)

[From: david.hazel at enchaine.com]

>The good news is that we are getting an increasing interest from
>developers with a background strong in mobile development but not
>specifically on Linux. 
>
>On Tue, 2007-08-28 at 00:43 +0200, ext koos vriezen wrote:
>> Hm, maybe we should start a Wiki page 'Getting started with Linux
>> using N880/N770' ...
>
>Any help in this direction is welcome, starting with the own non-Linux
>developers reporting and documenting the main issues they encounter. 
>

>From my perspective, there have been two distinct areas where I've needed help:

1. Linux development in general. There is some documentation out there, especially regarding GTK+, Gnome and GLib, but it doesn't appear to be 100% documented, it isn't easy to find the documentation on some calls (e.g. GLib versions of standard things, such as g_free(), etc.), and what documentation does exist doesn't appear to start from a high-level overview of what the thing (i.e. GTK+, Gnome or GLib) actually does or how its various function groups are intended to be used.

2. Maemo in particular (or Scratchbox, or Hildon - I'm still not clear on the distinction between these, as there is no single place where they are all discussed and compared). It took me ages even to find the HTML pages that describe the Hildon API, and even then it was incomplete. I'm still under the impression that many areas of interaction with the N800 are under-supported from an OS/API point of view (for example, is it possible, with a simple set of calls, to get an enumerated list of memory cards, so that one can scan them to see which one contains which files or obtain other information about them?) Maybe this impression is wrong, but if so it's because I haven't yet found any documentation that tells me otherwise.

It would also be useful to have a list of areas where the Scratchbox emulator currently does not implement all of the features on the N800. I'm finding, for example, that my Scratchbox doesn't provide the full set of applications that are present on my N800 (e.g. there is no Connection Manager, and no File Manager).

(By the way, on the question of semantics, the Scratchbox thingy IS an emulator, even though it is running the same software as the N800. It doesn't have the same hardware environment as the latter, so it has no choice but to simulate this in software. This kind of environment is universally referred to as an emulator, or a simulator, in software engineering circles.)

Finally, I'm finding that there is an over-reliance on 'examples' (which really seems to mean endless reams of other people's code) rather than proper descriptions of how things should be done. I've spent 24 years of my professional life reading other people's code. It's tedious, error-prone, and always open to the question "just because they've done it like that, does that mean this is how it's supposed to be done?" It's also a lot more time-consuming to read such code and work out how it relates to ones own requirements than to read a proper description (with small code examples if that helps illustrate things). I realise it's harder to WRITE the proper description than just do a brain-dump of ones own code, but it's certainly more helpful to the newcomer.

>We are starting to produce official documentation targeting developers
>with different backgrounds than Linux to help them land in the maemo
>context. These docs will be included in the maemo 4.0 release.

For ideas on what is needed, have a look at some of the published books on, say, WinAPI or Java. Alternatively, look at how Apple do it with the documentation they've produced for Mac OS X. The latter is a supreme example of well-written, carefully-crafted documentation (and, in fact, of a thoroughly well-engineered operating system and associated software technologies). Yes, there's an awful lot of it, but it's better to have that than too little.

If the answer to the last point is that 'free' documentation of that quality simply can't be produced on a part-time basis, well, I'm open to suggestions. I often write in my spare time, and I have a colleague who specialises in writing text books on various computing themes (his name is Nat McBride - look him up on Amazon). I also have a window opening in my availability after 7th September. Maybe Nokia would be prepared to fund someone to write some suitable documentation? After all, it would be in their interests for the wider developer community to be up to speed on this technology (otherwise it will die a death through lack of support). If anyone from Nokia is interested in this suggestion, and wants to take it further, let me know. I'd be happy to discuss things in more detail.

David Hazel