[IAEP] Feedback request for my Python tutorial

[Dinko Galetic]

Hi Caryl,

My first email was written in haste so I didn't explain what I am aiming at
with my tutorial, so I'll do that now. I think it should answer some of your
questions.

The materials I've send to the list are pure text. I mainly aimed this at
the discussion about the content, not the form, of the tutorial (are the
sentences clear enough, could certain things be explained better, etc.)

My intention is that this tutorial is used from Pippy in the same way the
current examples are. The content of the tutorial (the pure text I've mailed
to the list) would be wrapped in Python code so that it displays text one
paragraph at the time, is interactive (the learned can type code and
practice), offers the options to save progress, quit, continue etc. Since
the code for that would look quite intimidating[1] to the learner, it would
be hidden, most likely in /pippy/library/pippy/tutorial. The learner would
directly use files in /pippy/data/tutorial, the same way the currect Python
examples are used from Pippy. Those files (like this one [2]) would only
have something like:

import lesson1
lesson1.run()
# some comments on how to use the tutorial
# and what can be learned from this lesson

There are also some notes in the materials which will not be something the
learner will see; I've just marked places where I need to think more about
something or where a prompt will be.

On Tue, Jul 6, 2010 at 7:22 AM, Caryl Bigenho <cbigenho at hotmail.com> wrote:

>  Hello Dinko,
>
> This is a nice project and I will take some time over the next week or 2 to
> look at it in detail.  I notice a few "typos" that I can help with and will
> send them along later.  However I do have a question and a couple of
> suggestions at this point after glancing at the download.
>

I appreciate all the help I can get - even if it's about typos (in fact, I'm
curious about where you found them, I had everything checked before I posted
to the list).

Question: Why are some sections unix files and others plain text?  What are
> we supposed to open the unix files on?
>

There's no such thing as a unix file - those are all just standard plain
ASCII text files. In fact, all of them are in exactly the same format. I
accidentally named some of those differently (.txt). You should have no
problems opening them with your text editor.


>
> Suggestion: When a term is used in a Python tutorial do not assume your
> reader knows what it stands for or means. Keeping a glossary of terms will
> help teach the reader more than simple mysterious commands.  For example the
> > and < signs could be explained (very young readers will not know these).
>  Also the term "int." I assume it stands for "integer."  If so, tell us
> somewhere that it does and what an integer is. If not... what does it
> represent? Is it just a variable that you picked?
>
>
I see your point. A glossary is a good idea, I'll think of something.
However, there's one thing we should keep in mind. If there are readers
which don't know that < and > mean "less" and "larger", are you sure they
are of proper age to learn programming? While Sugar is for children from
6-12, I am aiming for the upper range of that age with my tutorial (they
should learn how read first, won't they :) ). I keep that idea in mind when
deciding if something is too advanced.

Regarding "int", I've mentioned that it is used to turn strings into a
number. The concept of integer is quite an advanced mathematical concept. I
do plan to talk a bit more about different number in later lessons, but I
decided to keep it short for now since most of the kids probably won't know
about decimal numbers so I didn't want to say "Look, int() gives you a whole
number, and float() a floating point number, which is a way numbers can be
binary represented... and we use that for decimal numbers..". In later
lesson, I do plan to mention it, but give a link to Wikipeda article on
floating point notation and say that they can read it there if they are
interested, but that it's enough to know it represents decimal numbers (and
also mention that they don't have to bother with it if they haven't learned
decimal numbers in school yet).



> Suggestion: Large blocks of text are very intimidating.  If you can break
> them up into smaller units (paragraphs) it will make it easier for the
> reader.
>

I have that in mind. There will always be a "Press enter to continue" prompt
after a block of text.


> Actually, it could also be helpful it the code part of your example was
> shown as you have it and the rest be in another font it will help the
> reader.
>

Well, if the tutorial was to be published on a website or in a book, sure.
However, it will be in a Python script


>
> I'm glad you have this project underway.  It will be very useful. When it
> is finished, we will need to get some people to translate it into other
> languages as well so OLPC users all over the world can enjoy using it.
>
> Caryl (aka SweetXOGrannie)
>


[1]
http://git.sugarlabs.org/projects/pippy/repos/dgaletic-gsoc2010/blobs/master/library/introduction.py
[2]
http://git.sugarlabs.org/projects/pippy/repos/dgaletic-gsoc2010/blobs/master/data/tutorial/Introduction
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.sugarlabs.org/archive/iaep/attachments/20100706/9b20076c/attachment.htm