Rethinking the Python tutorial

[Magnus Lycka]

Ed Singleton wrote:
> How about putting the current tutorial into the wiki and seeing if
> people start updating it?  I'm not saying it would work, but it might
> have interesting effects...

There are abviously a lot of ideas in the air concerning on-line
editing of the new python web site, support for user comments in
the docs etc. I hope some of these things will be deployed soon.

Concerning the tutorial, I just felt that the two I mentioned are
the "best of breed", and it might be smarter to give them official
status. I don't see any value in maintaining Guido's tutorial for
all eternity. It's not as if we need backward compatibility in the
tutorial department... I suppose there are some gaps in A Byte Of
Python that needs to be filled. For instance, the discussion on
Unicode seems very thin. I still think it's a better starting point
for the ideal beginners tutorial than the old official tutorial.

I still feel it's a better beginner's tutorial though. Last time I
suggested the standard Python tutorial to someone, she dropped
Python almost at once, since she got the impression that it was
some kind of calculator program, and she wasn't looking for that.

I think there are a lot of potential improvements for Python docs.
The Language Reference is unreadable for mortals, and that means
that there is no standard reference document describing the real
fundamentals in Python, statements and operators. we just have the
tutorial for that.

The best resource in the Python docs is that Library Reference.
As far as I understand, it's not complete, and it could contain
more examples in places, but it's very useful.

The Lanugage Reference seems more like some kind of specification.
I think a *real* Python Language Guide would be great, and it could
still be a fairly short document, even if core Python has grown a
bit in recent versions. The builtins chapter in the Library Reference
(Ch 2) belongs here, and the Std Lib Ref is just for things  we
import. It's really strange to document e.g. string literals and the
string class in different manuals.

I was thinking that maybe some old paper book on Python could be
donated for this purpose, but now it seems that most of the good
ones are going to be reprinted soon, if they aren't already in the
stores. I'm really happy that they are still commercially viable,
but it would have been great if we had gotten one of these goodies
as a starting point. It's hard work to write such good books as
e.g. Martelli and Beazley did.

Of the good books, I just have Beazley's "Python Essential Reference"
1st Ed. nearby, but chapter 2-10 in that shows very well what I
think a Python Language Guide could look like.

BTW... Alex is now employed by a very rich and successful company
that really owes the Python community a lot of gratitude. It's great
that they are paying the salaries for some of the very best Python
people, and let them work some for the community, but perhaps Google
could buy the rights for "Python in a Nutshell" from Martelli/O'Reilly
and donate it do the community? :)