[etoys-dev] Etoys documentation TOC

[Edward Cherlin]

On Thu, Sep 3, 2009 at 4:01 AM, Rita
Freudenberg<rita at 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 at squeakland.org
> http://lists.squeakland.org/mailman/listinfo/etoys-dev
>



-- 
Edward Mokurai Cherlin
Silent Thunder (默雷/धर्ममेघशब्दगर्ज/دھرممیگھشبدگر ج) is my name, and
Children are
my nation. The Cosmos is my dwelling place, the Truth my destination.
http://earthtreasury.org/