[maemo-community] Start of April_10 sprint: your action required

[From: Sebastian 'CrashandDie' Lauwers]

I'll chime in.

On Sat, Apr 10, 2010 at 6:35 PM, Andrew Flegg <andrew at bleb.org> wrote:

> Example problems (OTTOMH):
>  * Maemo 3 had Python documentation, but the canonical place for that
>    now is http://pymaemo.garage.maemo.org/
>  * Maemo 4 had lots of PDF documentation so isn't easy to search
>  * Maemo 5 has docs spread across the wiki (both current and archive),
>    Forum Nokia and so on.

> Now, I don't know how to solve this problem; perhaps one task could be
> to look at what other projects do about old API & reference
> documentation and come up with a strategy for Maemo? (Assuming we
> don't have one already :-))

I don't think it would be an easy task to try and look at other
projects, because there aren't that many projects that offer the same
problem.

I think there are a few things we should focus on:

- Realistically speaking, how many people are still developing for Maemo 3?
   In case the above number is low, maybe it would be an idea to
remove the Maemo 3 documentation from the search engines and clear up
the Maemo "namespace". We can still have an archive that is pointed to
clearly from the website, but just not indexed by bots.

- What types of development and documentation do we have?
   There are three types of developments going on. Maemo 3, Maemo GTK,
and Maemo Qt. The main focus of developers is C/C++ and Python.
      - The Maemo 3 documentation is historical and should just be a
matter of assembling it in one unique format, and then storing it --
no writing required.
      - Same thing for the Maemo GTK documentation, there is a lot of
it, spread across different media and websites, we need a task to
assemble it under one unique format, and then storing it (note, this
format should be editable for future contributors) -- Note: This can
cover Maemo 4 AND 5.
      - Maemo Qt: This is is the most active documentation set at the
moment, covering Maemo development, and later on being merged with
MeeGo. I believe we need to consult with the MeeGo project in order to
be future-proof, and help *them* re-use our documentation when the
time comes. Note: This can cover Maemo 4 AND 5.

So to recap: Maemo 3 doc goes in a dusty box in the attic, Maemo GTK
doc goes on a shelf, Maemo Qt doc stays on the desk.

Jaffa's JavaDoc example is an excellent one: it has easy to use
navigation and links, excellent overviews, introductions and abstract
examples, and easy to read function definition. However, there is one
thing around which it lacks quite severely, and that is tutorials and
examples.

I would like to see easy-to-use and easy-to-understand examples, in
small, bite-size chunks, properly documented and explained, in both
Python and C++. Maybe in a less-than-ideal example, the Microsoft MSDN
Library provides one feature which is quite interesting: you can
filter through languages. Articles can have multiple programming
languages, but by filtering, you only see the ones you want
information for (the articles are dynamically reformatted).

My $.02

-- 
question = ( to ) ? be : ! be;
      -- Wm. Shakespeare