[sugar] how does an activity connect to the journal?

[Christoph Derndorfer]

sugar-request at lists.laptop.org schrieb:
> ------------------------------
>
> Message: 8
> Date: Thu, 28 Feb 2008 11:57:25 -0500
> From: "Eben Eliason" <eben.eliason at gmail.com>
> Subject: Re: [sugar] how does an activity connect to the journal?
> To: "Paul Fox" <pgf at foxharp.boston.ma.us>
> Cc: Sugar Mailing List <sugar at lists.laptop.org>
> Message-ID:
> 	<948b197c0802280857yd41da5do778e68f7c161553b at mail.gmail.com>
> Content-Type: text/plain; charset="iso-8859-1"
>
> On Thu, Feb 28, 2008 at 11:51 AM, Paul Fox <pgf at foxharp.boston.ma.us> wrote:
>
>   
>> tomeu wrote:
>>  >
>>  > Yeah, it's a very important concept and perhaps it's not clearly
>>  > stated in the wiki documentation. Do you have any idea about how to
>>  > improve this? Perhaps the HIG should make this clearer?
>>
>> it may be there already.  i need to spend some more "quality time"
>> with the HIG document.
>>     
>
>
> Heh, me too, and I'm the one writing (or rather, who wrote) most of it.
>  Unfortunately, it's been stagnant for quite some time and needs a major
> refresh.  I think it should still provide a pretty solid overview of all the
> major concepts, though some details may not be fully accurate at this point.
> Your thoughts on its current state and areas for improvement would be much
> appreciated.  Thanks!
>   
As I'm currently working on the chapter about GUIs for our Activity 
Handbook 
(http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook) I've 
been spending quite a lot of the time on the [[HIG]] pages lately. In 
general I feel that they're very well written and I also always 
recommend them as must-read to anyone who's interested in Sugar or 
writing activities.

Apart from the missing sections towards the end I also have a couple of 
other comments and suggestions:

First of all I feel that the API References deserve more love. The 
reference entries themselves definitely need to be extended in order to 
be really useful to (new) developers. I've been trying to do that in the 
Activity Handbook by including short code-snippets for some of the 
things one can do with e.g. the toolbox/toolbar:

--- snip ---

As mentioned above the standard activity toolbar comes with both the 
"Share with" combo-box and the "keep"-button enabled. For situations 
where these elements aren't needed we can simply hide them by setting 
their "visible" property to "False". Below you can find a code-snippet 
that does exactly that:

<code>
# Loads the activity toolbar
activity_toolbar = toolbox.get_activity_toolbar()
# Hides the "Share with:" combo-box
activity_toolbar.share.props.visible = False
# Hides the keep button
activity_toolbar.keep.props.visible = False
</code>

--- snip ---

I'm not sure how much code belongs into the [[HIG]] itself (probably 
none!) but I definitely think that kind of information needs to be tied 
in by linking to relevant resources.

Secondly I believe that more information about collaboration should be 
included. Right now for example we have many activities that come with a 
"share with:" button but don't actually do anything. So how much of a 
requirement is collaboration actually? Is it okay to have single-player 
games and single-user activities or should everyone really try to allow 
for multiple people to work on an activity?

Another thing that might be useful is a list of "do"-s and "don't"-s. 
I'm sure that Eben and many other have come across activities that 
seemed to do something particularly well or not so well and these 
examples could be used as case-studies. Right now some elements such as 
the toolbars are very well explained but what at least I'm looking for 
is a closer explanation of how different elements should or shouldn't be 
tied together. All in all I believe we can all learn a lot from the 
mistakes that others have made.

Cheers,
Christoph

> - Eben
>
>