[sugar] Docs?

[Walter Bender]

Your list is a good one, but I think what could be a real boost to
developers would be a simple step-by-step guide to taking an existing
application and porting it to the laptop. This itself is a
multifaceted task that can be done incrementally: making it work
within the restraints of the libraries on the XO, making it work in a
way that takes advantage of the display, making it work within the
basic Sugar framework, making it work within the basic mesh framework,
making it work within the context of view-source...

Probably the game folks are farther along in this than most...

thanks.

-walter

On 8/5/07, Mel Chua <metamel at gmail.com> wrote:
> Speaking of getting external/local parties to document the "high ceiling"...
>
> Adam Hyde, who runs http://flossmanuals.net/, has offered to mobilize a
> FLOSSmanuals project(s) for moderately "polished" multilingual documentation
> of the XO for developers, endusers, or both (w/ easy access to nice
> print-on-demand books - potentially handy for developers who want to carry a
> nicely-bound reference/quickstart around with them.) He'd especially like to
> develop a minimally verbal (as close to 100% icon/photo based as possible)
> set of documentation, and tools for creating such, so that devels can
> quickly document their work with very little need for translation, and
> students/teachers with XOs can easily contribute.
>
> Is this along the lines of what folks were thinking? Is there a particular
> project that would be good to point him towards? I was thinking of
> suggesting a "new developers guide" which would include user-friendlifying /
> de-acronymizing / translating / coherently-ordering existing pages like
>
> http://wiki.laptop.org/go/Hardware_specification
> http://wiki.laptop.org/go/Developers_program
> http://wiki.laptop.org/go/Emulation
> http://wiki.laptop.org/go/Demo_Notes (updated for either B4
> or the production machine)
> http://wiki.laptop.org/go/Game_Development_Quickstart
> etc.Thoughts?
>
> -Mel
>
>
> On 8/6/07, Mike Usmar <mike at mikeusmar.com> wrote:
> > While I agree there is some more work needing to occur to fast track
> > developers into coding, I am confident that the UI guidelines, and indeed
> > sugar are intuitive enough that children "get it" rather fast. We have
> been
> > mass testing the user experience both with emulators and XO's here in a
> > Pacific Island community in New Zealand - with about 11 languages in one
> > class room at once, and the User Experience isn't an issue. We took 5 XO
> up
> > to a school in Fiji on Friday, a school in the middle of the bush, and
> > within minutes of the children seeing the XO they we recording, and
> creating
> > a slide show - the thing to note here is they had never seen a computer
> > ever! This teachers us volumes - be confident that kids in underdeveloped
> > countries are very smart, and even more keen to discover
> >
> > Mike Usmar
> > OLPC NZ/Pacific Development Group
> > University of Auckland/Computer Clubhouse
> > DDI 64 9 271-1907
> > SKYPE: mikeusmar
> >
> >
> > On 2/8/07 12:52 PM, "Walter Bender" <walter.bender at gmail.com> wrote:
> >
> > > One thing we have been lagging behind on is documentation for
> > > developers: APIs, etc. Eben has done a nice job on the UI guidelines,
> > > but there more help we can and should provide to those who want to dig
> > > into the code itself--something we are encouraging the children and
> > > teachers to do.
> > >
> > > -walter
> > >
> > > On 8/1/07, Eben Eliason <eben.eliason at gmail.com> wrote:
> > >> We're not ignorant of the need for some amount of explanation about
> various
> > >> aspects of the UI and also some activities.  For the most part, we do
> feel
> > >> that the interfaces will offer an immediately usable or at least
> quickly
> > >> discoverable experience for most, and this has been true in some early
> > >> trials with much earlier (and buggier) versions of the software.
> > >> Nonetheless, we wouldn't presume that it will be "obvious" to all.  For
> that
> > >> matter, some of the advanced functionality that provides the high
> ceiling in
> > >> our "low floor, high ceiling" model may actually be less discoverable
> in
> > >> favor of a simpler up front experience, and in those cases
> documentation can
> > >> be a valuable thing.
> > >>
> > >> In any event, this project is about both education and community.
> These two
> > >> items should re-factor the way we think about help.  Yes, we'll provide
> some
> > >> basic documentation; yes, activity developers will do the same.  But in
> the
> > >> long run, it's much more consistent with our goals for the project to
> create
> > >> an ever growing community around the laptops and their activities,
> where
> > >> children, teachers, and developers alike can post tips, suggestions,
> formal
> > >> documentation, images, video, experiences, and tutorials about both
> software
> > >> and hardware.  In this way, we can leverage the power of the
> communities and
> > >> the children themselves, who are eager to explore and learn, and can
> learn
> > >> how to help each other through the process.  By handing out some
> > >> responsibility, the localization problem can be solved naturally.
> Having an
> > >> evolving system for help also makes a lot of sense when the software is
> both
> > >> young and continually changing.
> > >>
> > >>
> > >> We're not neglecting help on principle; we're adjusting our view of the
> help
> > >> model in light of the project's mission and goals.
> > >>
> > >> - Eben
> > >>
> > >>
> > >> On 8/1/07, Ryan Pavlik <abiryan at ryand.net> wrote:
> > >>> I am not coming up with these ideas, just relaying them.  If you wish
> > >>> for comment by the entire community, including those who know more
> about
> > >>> it than me, use the "Reply to All" feature of your mail client rather
> > >>> than sending private replies - I am rather unqualified to answer most
> of
> > >>> your questions.
> > >>>
> > >>> Ryan
> > >>>
> > >>> dthornburg at aol.com wrote:
> > >>>> Dear Ryan,
> > >>>>
> > >>>> I don't doubt the solid pedagogical underpinnings of the OLPC, and
> > >>>> fully endorse the principles.  As the 25th employee at Xerox PARC I
> > >>>> have more than a passing interest in user interfaces, and I applaud
> > >>>> Sugar's innovative approach (and talk about it in many of my
> > >>>> presentations).  That said, my experience using technology with kids
> > >>>> since the 1970's has revealed different levels of "obviousness," and
> > >>>> this is reflected in the many spirited discussions on this list.
> > >>>> Pardon me if it appears that the idea of "obviating the need for
> > >>>> documentation" is slightly hubristic.  There will be some (especially
> > >>>> among the adult decision-making community) who will benefit from some
> > >>>> documentation.  Are you suggesting that (for example) eToys needs no
> > >>>> documentation?  If so how do you explain that the first Smalltalk
> > >>>> documentation consisted of TWO hardbound books published by
> > >>>> Addison-Welsey.
> > >>>>
> > >>>> I am a huge fan of having kids jump into the deep end of new
> > >>>> projects.  I also have found that helpful resources are quite
> valuable.
> > >>>>
> > >>>> Warm regards,
> > >>>>
> > >>>> David Thornburg, PhD
> > >>>> Director, Global Operations
> > >>>> Thornburg Center
> > >>>> Chicago, USA | Recife, Brasil
> > >>>>
> > >>>>
> > >>>> -----Original Message-----
> > >>>> From: Ryan Pavlik < abiryan at ryand.net>
> > >>>> To: dthornburg at aol.com; Sugar Mailing List < sugar at lists.laptop.org>
> > >>>> Sent: Tue, 31 Jul 2007 11:57 pm
> > >>>> Subject: Re: [sugar] Docs?
> > >>>>
> > >>>> By self-documenting I mean that the interface obviates the need for
> > >>>> documentation, not that it produces written documentation. You might
> > >>>> be interested to look at http://wiki.laptop.org - it is as much
> > >>>> (more!) an education project as a laptop project, and the educational
> > >>>> theory behind the decision decisions is pretty interesting.
> > >>>>
> > >>>> Ryan
> > >>>>
> > >>>> dthornburg at aol.com <mailto:dthornburg at aol.com> wrote:
> > >>>>> If the OLPC is self-documenting, who is handling this, how much
> > >>>> memory > does it take, and what does the interface look like? It
> seems
> > >>>> that > this would have come up in conversations by now.
> > >>>>>
> > >>>>> Just asking.
> > >>>>>
> > >>>>> David Thornburg
> > >>>>>
> > >>>>>
> > >>>>> -----Original Message-----
> > >>>>> From: Ryan Pavlik <abiryan at ryand.net <mailto:abiryan at ryand.net >>
> > >>>>> To: Edward Cherlin < echerlin at gmail.com <mailto:echerlin at gmail.com>>
> > >>>>> Cc: sugar at lists.laptop.org <mailto:sugar at lists.laptop.org>
> > >>>>> Sent: Tue, 31 Jul 2007 7:35 pm
> > >>>>> Subject: Re: [sugar] Docs?
> > >>>>>
> > >>>>> I am certainly not an OLPC rep, but what I have seen suggests that
> > >>>> the >
> > >>>>> intent is for the machines to be self-instructing and not requiring
> >
> > >>>>> documentation. In addition to the massive translation demands that >
> > >>>>> would require, it also does not coincide with the educational >
> > >>>>> theories/practices that the organization is pursuing.
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> Of course, if you want to make developer documentation, then I think
> >
> > >>>>> anyone's answer would be, dive in! :) Just ask which regions are
> > >>>> stable >
> > >>>>> first so your work doesn't get obsoleted quickly.
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> Ryan
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> Edward Cherlin wrote:
> > >>>>>
> > >>>>>> Is there any plan for official software documentation? I have been
> > >>>> a >
> > >>>>>> Senior Tech Writer for the last 10 years and would be delighted to
> >
> > >>>>>> work on it (particularly if someone like Red Hat would support me
> > >>>> to >
> > >>>>>> do it 60 hours a week *<{%-{]}}} <--Goggle-eyed geek in clown hat,
> >
> > >>>>>> moustache, and full beard). Actually, I have been writing about XO
> >
> > >>>>>> software off and on ever since the Dynabook days, when Xerox
> > >>>> licensed >
> > >>>>>> Smalltalk to Apple, HP, and others in 1981, during my market
> > >>>> research >
> > >>>>>> period.
> > >>>>>
> > >>>>>>
> > >>>>>
> > >>>>>> For example, I wrote in a study of so-called educational software
> > >>>> back >
> > >>>>>> then that the overpriced drill-and-practice programs of the time >
> > >>>>>> weren't real educational software, and that what children need is >
> > >>>>>> sharp tools to do stuff with. Commercial educational software is
> > >>>> still >
> > >>>>>> a vast wasteland, with a few honorable exceptions. Then I did a
> > >>>> study >
> > >>>>>> on Personal Instruments (data acquisition and analysis on PCs), and
> > >>>
> > >>>>>> some other reports that touched on education. Besides starting and
> >
> > >>>>>> managing a software project for math for schools. And a few other
> > >>>> things.
> > >>>>>
> > >>>>>>
> > >>>>>
> > >>>>>> I have a button that says, "Stop me before I volunteer again," but
> > >>>> it >
> > >>>>>> doesn't help. [sigh]
> > >>>>>
> > >>>>>>
> > >>>>>
> > >>>>>> -- >
> > >>>>>> Edward Cherlin
> > >>>>>
> > >>>>>> Earth Treasury: End Poverty at a Profit
> > >>>>>
> > >>>>>> http://wiki.laptop.org/go/Earth_Treasury
> > >>>>>
> > >>>>>> WIRE AFRICA http//www.wireafrica.org/ < http://www.wireafrica.org/>
> > >>>> <http://www.wireafrica.org/>
> > >>>>>
> > >>>>>> http://www.linkedin.com/in/cherlin
> > >>>>>
> > >>>>>>
> > >>>>
> > >>
> ------------------------------------------------------------------------
> > >>>>>
> > >>>>>>
> > >>>>>
> > >>>>>> _______________________________________________
> > >>>>>
> > >>>>>> Sugar mailing list
> > >>>>>
> > >>>>>> Sugar at lists.laptop.org <mailto:Sugar at lists.laptop.org >
> > >>>> <mailto: Sugar at lists.laptop.org <mailto:Sugar at lists.laptop.org?>>
> > >>>>>
> > >>>>>> http://lists.laptop.org/listinfo/sugar
> > >>>>>
> > >>>>>>>
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> -- >
> > >>>>> Ryan Pavlik
> > >>>>>
> > >>>>> AbiWord Win32 Platform Maintainer, Art Lead: www.abisource.com
> > >>>> <http://www.abisource.com > <http://www.abisource.com>
> > >>>>>
> > >>>>> AbiWord Community Outreach Project:
> > >>>> www.cleardefinition.com/oss/abi/blog/
> > >>>> <http://www.cleardefinition.com /oss/abi/blog/>
> > >>>> < http://www.cleardefinition.com/oss/abi/blog/>
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> "Optimism is the father that leads to achievement."
> > >>>>>
> > >>>>> -- Helen Keller
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> "The folder structure in a modern Linux distribution such as Ubuntu
> > >>>>>
> > >>>>> was largely inspired by the original UNIX foundations that were
> > >>>>>
> > >>>>> created by men with large beards and sensible jumpers."
> > >>>>>
> > >>>>> -- Jono Bacon, The Ubuntu Guide
> > >>>>>
> > >>>>>
> > >>>>>
> > >>>>> ______________________________ _________________
> > >>>>>
> > >>>>> Sugar mailing list
> > >>>>>
> > >>>>> Sugar at lists.laptop.org <mailto:Sugar at lists.laptop.org >
> > >>>> <mailto:Sugar at lists.laptop.org <mailto:Sugar at lists.laptop.org?>>
> > >>>>>
> > >>>>> http://lists.laptop.org/listinfo/sugar
> > >>>>>
> > >>>>
> > >>
> ------------------------------------------------------------------------
> > >>>>> AOL now offers free email to everyone. Find out more about what's
> > >>>> free > from AOL at *AOL.com*
> > >>>> < http://www.aol.com?ncid=AOLAOF00020000000437>.
> > >>>>
> > >>>> -- Ryan Pavlik
> > >>>> AbiWord Win32 Platform Maintainer, Art Lead: www.abisource.com
> > >>>> <http://www.abisource.com>
> > >>>> AbiWord Community Outreach Project:
> > >>>> www.cleardefinition.com/oss/abi/blog/
> > >>>> <http://www.cleardefinition.com/oss/abi/blog/>
> > >>>>
> > >>>> "Optimism is the father that leads to achievement."
> > >>>> -- Helen Keller
> > >>>>
> > >>>> "The folder structure in a modern Linux distribution such as Ubuntu
> > >>>> was largely inspired by the original UNIX foundations that were
> > >>>> created by men with large beards and sensible jumpers."
> > >>>> -- Jono Bacon, The Ubuntu Guide
> > >>>>
> > >>>>
> > >>
> ------------------------------------------------------------------------
> > >>>> AOL now offers free email to everyone. Find out more about what's
> free
> > >>>> from AOL at * AOL.com*
> <http://www.aol.com?ncid=AOLAOF00020000000437 >.
> > >>>
> > >>>
> > >>> --
> > >>> Ryan Pavlik
> > >>> AbiWord Win32 Platform Maintainer, Art Lead: www.abisource.com
> > >>> AbiWord Community Outreach Project:
> www.cleardefinition.com/oss/abi/blog/
> > >>>
> > >>> "Optimism is the father that leads to achievement."
> > >>> -- Helen Keller
> > >>>
> > >>> "The folder structure in a modern Linux distribution such as Ubuntu
> > >>> was largely inspired by the original UNIX foundations that were
> > >>> created by men with large beards and sensible jumpers."
> > >>> -- Jono Bacon, The Ubuntu Guide
> > >>>
> > >>> _______________________________________________
> > >>> Sugar mailing list
> > >>> Sugar at lists.laptop.org
> > >>> http://lists.laptop.org/listinfo/sugar
> > >>>
> > >>
> > >>
> > >> _______________________________________________
> > >> Sugar mailing list
> > >> Sugar at lists.laptop.org
> > >> http://lists.laptop.org/listinfo/sugar
> > >>
> > >>
> > >
> >
> >
> > _______________________________________________
> > Sugar mailing list
> > Sugar at lists.laptop.org
> > http://lists.laptop.org/listinfo/sugar
> >
>
>


-- 
Walter Bender
One Laptop per Child
http://laptop.org