[sugar] Docs?

[Walter Bender]

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
>
>


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