[sugar] Docs?

Sun Aug 5 21:18:31 EDT 2007

Speaking of getting external/local parties to document the "high ceiling"...

Adam Hyde, who runs http://flossmanuals.net/, <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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.laptop.org/pipermail/sugar/attachments/20070806/fba1b489/attachment-0001.htm 