On Sep 3, 2009, at 7:01 AM, Rita Freudenberg wrote:

Hi all,

as you all know we don't really have an Etoys documentation. So let's start writing it. As I wrote earlier I propose to use FLOSS Manuals. It is used by the olpc and sugar community for writing manuals and books. To get started we should have a TOC outline. Here are my suggestions:

1. Introduction (short description what etoys is about)
2. Getting started (technical description on how to install and

start etoys on different operating systems) 3. User Interface (painting tools, halo, viewer ...) 4. Tiles (describing every available tile) 5. Objects (everything from the supplies bin and object catalogue, flaps)

What am I missing? Of course we can have subchapters and also later add main chapters if we find out we need it. Here is the manual for TurtleArt so you can get the idea what our documentation could look like: http://en.flossmanuals.net/turtleart

What do you think? If we come up with a TOC outline I can send it to Anne Gentle from FLOSS manuals to set it up and we can start writing:)

It's a good list. So this would be more of a reference manual than a getting started guide? (with tutorials)

We could link back to the Etoys unit of the courseware for the gentler intro.

Tim

On Sep 3, 2009, at 7:01 AM, Rita Freudenberg wrote:

Hi all,

as you all know we don't really have an Etoys documentation. So let's start writing it. As I wrote earlier I propose to use FLOSS Manuals. It is used by the olpc and sugar community for writing manuals and books. To get started we should have a TOC outline. Here are my suggestions:

1. Introduction (short description what etoys is about)
2. Getting started (technical description on how to install and

start etoys on different operating systems) 3. User Interface (painting tools, halo, viewer ...) 4. Tiles (describing every available tile) 5. Objects (everything from the supplies bin and object catalogue, flaps)

What am I missing? Of course we can have subchapters and also later add main chapters if we find out we need it. Here is the manual for TurtleArt so you can get the idea what our documentation could look like: http://en.flossmanuals.net/turtleart

What do you think? If we come up with a TOC outline I can send it to Anne Gentle from FLOSS manuals to set it up and we can start writing:)

Also, just want to highlight that we actually do have some documentation (with even a big PDF):

http://squeakland.org/tutorials/guides/

Kathleen's work is concise and useful, and should be used where possible in the FLOSS version.

Tim

On Thursday 03 Sep 2009 4:31:55 pm Rita Freudenberg wrote:

2. Getting started (technical description on how to install and start

etoys on different operating systems)

IMHO, we should separate technical reference from learner's reference. Installation is something that is done once while learning happens all the time.

Existing guides (e.g. Powerful Ideas, help) use a prescriptive style (press this, do this etc.). Many beginners get into a mechanical action mode. IMHO, children (and teachers) need a conceptual style that helps them transition from real world to digital world. A lesson I learnt the hard way :-(.

Nowadays I introduce Etoys as a kit containing thousands of 'tiny powerful automatic computers'. They have a button panel (halo buttons) and keyboard (for text entry) but no 'form'. We paint a shape or stick a graphic label to recognise and manipulate them. These computers can memorize stuff and follow instructions but they have no will or consciousness of their own. So we have to "think" for them and give them right instructions. We can also get two or more "computers" to work together as a team ("pick up your heading from wheel's heading", align next to, move towards etc). Such a team of computers can be used to tell a story ("water cycle"), calculate magnitudes ("if I walk 10 units north and then 10 units east, how far am I from the starting point?") or model things around us ("seeds on a sunflower") to discover patterns.

I hope I am too off the mark here. Originally, the term "computer" referred to a smart person who did calculations. Later, electronic machines were designed to mimic their operations and these were dubbed "automatic computers".

Subbu

On Thu, Sep 3, 2009 at 4:01 AM, Rita Freudenbergrita@isg.cs.uni-magdeburg.de wrote:

Hi all,

as you all know we don't really have an Etoys documentation. So let's start writing it. As I wrote earlier I propose to use FLOSS Manuals. It is used by the olpc and sugar community for writing manuals and books.

Hooray! I'm a writer and editor for FM, and as it happens I need a manual on Etoys myself.

To get started we should have a TOC outline. Here are my suggestions:

Before we come to that, I have a question. Should this be a book (PDF, print, or other format), or should it all be done in Etoys?

1. Introduction (short description what etoys is about)

Education, right?

2. Getting started (technical description on how to install and start etoys

on different operating systems)

Please don't call this Getting Started. That's the chapter _after_ installation. We can call this Getting Set Up, or Installation, or perhaps we can think of something more informative to our novice audience.

2.1 Getting Started

Where, in fact, do I start? Well, we have lots of projects to look at in Etoys, and a few tutorials. We need at least one more tutorial, about how to start a new project, either from scratch or more likely by modifying an existing project. We also need a way to show people how to discover almost everything in Etoys themselves. That means that we need to determine what they will not be able to discover, so that we can show them those bits while sending them exploring, and have them end up competent to go on as far as they like.

You can get an idea of what I mean from the list of undiscoverable elements of Sugar, at http://wiki.sugarlabs.org/go/The_undiscoverable.

As with Alan Kay's favorite demo, the gravity lesson, we want to find the minimum set of hints for people to discover each of the things they probably won't find on their own. We know that people generally need some degree of help with

o Tool halo

o Object viewer

o Toolbox

o What objects are, and how they work

o Creating or modifying an object

o What can I safely modify, without breaking Etoys? (Redefining 2 is definitely not safe. ^_^)

o Starting a project

o Smalltalk language features, including some of the syntax and the high-level object types

o Design

o Documentation

o Where to get help

What else?

3. User Interface (painting tools, halo, viewer ...)
4. Tiles (describing every available tile)
5. Objects (everything from the supplies bin and object catalogue, flaps)

This is the outline of a reference manual, not an introduction. Do we need a reference manual, when Etoys is so self-documenting? Maybe, but let's start over on the Etoys for Prospective Etoys Users, to be renamed when we work out what will be in it.

What are we trying to accomplish? What is the elevator pitch to the reader who has happened on our material? The answer is not "Learn Smalltalk". It is not, "Easy, powerful development". Why is it neither of these? To answer that, we have to ask ourselves, "What questions might the reader be asking?" What question would the reader say is foremost? What other questions does the reader have in mind? What questions did the reader not know to ask? What are the key questions in the reader's life that Etoys bears on?

Turn that around. People come with all sorts of questions. Which ones resonate with our questions? I am here to give a billion children a real education, to get them all into a collaboration on designing the future and solving the myriad little daily problems like oppressive governments, corruption, racism, and the rest of the nastiness, brutality, and shortness of life for the poor of the world. And how to be happy in the midst of it all. Why are you here?

So I am looking for the requirements on an introduction to Etoys for students, teachers, parents, school officials, governments, developers of educational software and learning materials, and several other such audiences. Can we do all of them? Yes, if we take a little time to think, and to ask what their needs are. Each one needs an entry point into the main material that addresses their issues, assuages their concerns, gives them a path forward beyond this one book.

Here is a question that not everyone will know to ask.

What sort of education do we have in mind?

o Not the traditional factory-automation model of the same lesson from the same book on the same day in every school in a country. We have the means to provide much deeper understanding and competence than such schools have provided.

o Not the tyranny of the Right Answer, when all of the important questions don't have Right Answers. Is this Real? Is this True? How do I know? Should you believe me? What should we do next, even if we don't want to?

What we want to provide is somewhat nebulous, because in fact this is also a question without a Right Answer. But we know at least that we want to help children

o Learn how to learn _anything_.

o Discover as much as possible for themselves

o Learn how to work together effectively

o Learn how to make things, and then how to improve them

o Learn what science is, how to do it, and how to use it. Not just the facts and the theories, but the methods.

o Learn to detect nonsense--guff, bogosity, bafflegab, bunk, propaganda, myth, conventional wisdom, groupthink,...even outright lies.

o Be able to think of more than one part of an elephant at a time

So, further questions can be

o Why is Smalltalk easier for teachers, students, and parents than any other computer language?

o In what ways is Smalltalk designed for childhood education?

o What materials exist in Smalltalk

o Does all of that work? (In the jargon: Are there peer-reviewed studies showing measured improvements in educational outcomes?

What am I missing? Of course we can have subchapters and also later add main chapters if we find out we need it. Here is the manual for TurtleArt so you can get the idea what our documentation could look like: http://en.flossmanuals.net/turtleart

See also http://wiki.sugarlabs.org/go/Activities/Turtle_Art#Palettes for another style of introduction.

What do you think? If we come up with a TOC outline I can send it to Anne Gentle from FLOSS manuals to set it up and we can start writing:)

Here is mine. These are not necessarily the actual section titles. I have included a bit of extra explanation that can go into the first paragraph in the real materials.

What is Etoys, and why do I care? Getting Etoys installed and Ready to Go Your First View What am I looking at? Project Library Elementary tutorials Do It Yourself Objects in the View Discovering Etoys You can't break anything "So simple a ten-year-old can understand it. Quick, get me a ten-year-old."--Groucho Marx Try left-click, right-click, click-and-drag on _everything_. Yes, _everything_ Make notes on anything that you can't figure out just by clicking. We'll help you. FAQ--Everything that users couldn't figure out on their own. Exploring Tools and Supplies Project Library Tutorials Tool Halo Toolbox Making and Changing Objects Creating Projects Drawing Multimedia Modifying Objects Creating Object Types Models The World Outside Smalltalk Programming How to Say It What It Does Design and Redesign Thinks That Work With Other Things (Cooperating Sequential Processes, Objects) Do I Understand What I am Doing? What Might I Want to Change Later? What Should I Build First? Does It Do What I Meant? How Do You Get Etoys to Do That? A Progression of Little Projects Algorithms + Data Structures = Objects School Subjects in Etoys Powerful Ideas in Etoys Answering Questions Questioning Answers Now What?

Greetings, Rita

-- Rita Freudenberg FIN-ISG Otto-von-Guericke-Universität Magdeburg http://isgwww.cs.uni-magdeburg.de/isg/rita.html

---

etoys-dev mailing list etoys-dev@squeakland.org http://lists.squeakland.org/mailman/listinfo/etoys-dev