[FM Discuss] I'd like to write a manual on Beginner's Guide To Creating Sugar Activities

[Jim Simmons]

Anne,

I understand where you're coming from on this, but I think that the
subject really deserves its own book.  The chapter in the Sugar book
on creating Activities is kind of thin, and if you made it much
thicker you might make the book less useful to its intended audience.
I see this as an O'Reilly book for the pre-teen set and up, or better
still like one of the Alfred P. Morgan books I loved in the sixth
grade ("The Boy Electrician" and many others).

There is already an Activity development book out there that is good
as far as it goes, but the material is dated and in fact there are
easier ways to create and test Activities than what they describe.  It
also assumes more knowledge than a beginner would have.

To give you some idea of the scope of this thing here is my table of
contents from Open Office so far:

Table of Contents
1 Introduction	3
2 What Is Sugar?	5
2.1 The Journal	6
2.2 Collaboration	7
2.3 Security	8
2.4 Summary	9
3 What Is A Sugar Activity?	11
4 What Do I Need To Know To Write A Sugar Activity?	12
4.1 Python	12
4.2 PyGTK	13
4.3 PyGame	13
5 Setting Up a Development Environment	15
5.1 Linux or Emulation?	15
5.2 Eric	17
5.3 Inkscape	17
5.4 The Sugar Environment	17
5.5 Should I Use sugar-jhbuild?	18
6 Creating Your First Activity	19
6.1 Make A Standalone Python Program First	19
6.2 Inherit From Activity	19

There's a *lot* more where that came from.  It's a huge subject.
Also, while the Sugar bok has a chapter titled "What is Sugar?"
already mine will be much different.  Mine will be a programmer's view
of Sugar that deals with things like the Journal and how you work with
it, Security and how it affects what your Activity can do and how it
does it, how Collaboration works and what you can do with it, etc.

A book like this needs code samples too, which may scare off readers
of the Sugar book.

I'm counting on contributions and feedback from others, of course.
There are topics that belong in a book like this that I'm not fully
qualified to write.  For instance, I've never done an Activity using
PyGame and I've never Sugarized an existing app written in a language
other than Python.  I've used Pootle for internationalizing my
Activities but I'm damned if I know if I'm doing it right.  I know a
bit about making an Activity support multiple versions of Sugar but
others know more.  And as you see above I'm going to recommend that
for testing purposes an Activity developer make a first version as a
program that can run outside of Sugar.  It sounds like Walter has
taken this idea farther than I have.

I am attracted to Floss Manuals because it seems to offer the
collaboration advantages of a Wiki with the structure of a book.
There are good articles in the OLPC and Sugar Wikis but if I was a kid
learning all this stuff for the first time I'd want a book.

In summary, I think what I'm proposing would not be a good fit in the
Sugar book.  They are aimed at two different audiences.  I might go so
far as to suggest that if this proposed book reaches a critical mass
you might consider taking the small amount of Activity creating
content out of the Sugar book and replacing it with a reference to
this new book.

Thanks for your consideration.

James Simmons


> Date: Fri, 18 Dec 2009 12:58:57 -0600
> From: Anne Gentle <annegentle at justwriteclick.com>
> To: discuss at lists.flossmanuals.net
> Subject: Re: [FM Discuss] I'd like to write a manual on Beginner's
>        Guide To        Creating Sugar Activities
> Message-ID:
>        <1a4c3e670912181058w61efb30ds8819ecb4ae009429 at mail.gmail.com>
> Content-Type: text/plain; charset=ISO-8859-1
>
> Wow, Jim, your proposed content sounds great. Would you consider
> making those chapters within the Sugar book itself? There is a
> Creating Activities chapter at
> http://en.flossmanuals.net/Sugar/CreatingActivities, and I would
> envision your experience and code examples would be a wonderful
> additional chapter to the "Extending Sugar" section.
>
> With this method, you can create your own book  as a remix, say
> "Beginner's Guide to Creating Sugar Activities" or "A Guide To
> Creating Sugar Activities For Beginners", but also your content
> becomes part of the bigger Sugar book. Then your content gets greater
> distribution and the Sugar book gets more content... I think that
> helps all around.
>
> Let me know what you think and I'll be happy to set up the chapter
> idea I'm thinking of if that'll help you visualize it.
>
> Walter, it'd be great to include that sprite library chapter as well,
> as another chapter within "Extending Sugar."
>
> Anne