[Its.an.education.project] Sugar documentation

[Wade Brainerd]

Here's what I would do with the Sugar documentation.  I wish I could
say I'm about to get started on it, but I'm stuck working crazy hours
until June at the earliest.

Step 1: Identify the target audiences.

1. Experienced developers who are looking to get started making Sugar
activities.
2. New developers who are learning to program on the XOs they received
in the deployments.

My feeling is that we should focus on #1 for now, but make allowances
for #2 to happen in the future.

Step 2: Identify the kinds of documentation needed.

1. Getting started documentation.  Quick steps for setting up a
development environment and building "Hello, world".  Ideal format:
Wiki.
1. Module API reference documentation.  Organized, clear, correct
description of each class, method, property.  Ideal format: PyGTK
exported to HTML, hosted on d.l.o, part of the build process.
2. Module Overview documentation.  Section by section description of
how to use the API to achieve goals.  Ideal format: Wiki.
3. Tutorial documentation.  Step by step examples of developing
activities with various features.  Simple programs which demonstrate
ONE thing, not large programs which try to demonstrate everything.
Ideal format: Snippets of example source code in Wiki with step by
step instructions, downloadable source code.
4. Process documentation.  Step by step instructions to do things like
create a new project, submit for project hosting, make a patch to an
existing activity, etc.

Step 3: Collect the existing documentation.

Go through the wiki and collect those pages with existing
documentation related to the areas identified in Step 2.  We should
also find all the useful external documentation sites (pygtk.org) that
are relevant.  I am happy to offer my list of bookmarks to anyone who
wants to start this effort.  The
http://wiki.laptop.org/go/API_Reference also has a wealth of links.
Pages should be organized into one of the Step 2 categories, and by
module (rainbow, activity, sugar graphics, datastore, etc).

Step 4. Build a Wiki portal for developer documentation.

The http://wiki.laptop.org/go/Developers/Documentation page should be
refactored to be the central place for all this stuff, currently it is
just a few loose links.  The API_Reference page has most of the
information (including links to examples) that should be on this page,
and there are other major pages that should be merged in as well.

I think the Wiki is the best place for all of this written stuff
because the barrier to community discovery and contribution is very
low, and it already has translation support which will ultimately
benefit target audience #2 when they appear.

------------------------------------------------

As an aside, I encourage anyone interested in helping with Sugar
documentation to check out Apple's iPhone SDK at
http://developer.apple.com/iphone/ (you must create an account to see
the documentation).

This is a new platform which isn't even officially available yet, but
the developer documentation is extremely well organized and complete.

Regards,

Wade