Rethinking the Python tutorial

[Magnus Lycka]

While the official Python Tutorial has served its
purpose well, keeping it up to date is hardly anyones
top priority, and there are others who passionately
create really good Python tutorials on the web.

I think 'A Byte of Python' by Swaroop C H is a good
beginners tutorial, and 'Dive Into Python' by Mark
Pilgrim is a good tutorial for more experienced
programmers.

My radical idea is that we mirror these at
diveinto.python.org and byteof.python.org, and
simply remove the old tutorial from the Python
2.5 (or 2.6?) docs. Give these two good texts an
official status as the Python tutorials.

Just as we want to adopt best of breed packages
for the standard library, I think we should use
best of breed documentation, and I think there are
less backward compatibility issues with tutorials
than with libraries.

I think this change would give us better docs as
well as a smaller maintenance burden. If a day
comes when Mark Pilgrim or Swaroop C H don't want
to maintain these texts, I strongly suspect that
there are other tutorials we can replace them with
if noone else steps in to keep them up to date.

 

[Ed Singleton]

While the official Python Tutorial has served its
purpose well, keeping it up to date is hardly anyones
top priority, and there are others who passionately
create really good Python tutorials on the web.

I think 'A Byte of Python' by Swaroop C H is a good
beginners tutorial, and 'Dive Into Python' by Mark
Pilgrim is a good tutorial for more experienced
programmers.

My radical idea is that we mirror these at
diveinto.python.org and byteof.python.org, and
simply remove the old tutorial from the Python
2.5 (or 2.6?) docs. Give these two good texts an
official status as the Python tutorials.

Just as we want to adopt best of breed packages
for the standard library, I think we should use
best of breed documentation, and I think there are
less backward compatibility issues with tutorials
than with libraries.

I think this change would give us better docs as
well as a smaller maintenance burden. If a day
comes when Mark Pilgrim or Swaroop C H don't want
to maintain these texts, I strongly suspect that
there are other tutorials we can replace them with
if noone else steps in to keep them up to date.

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...

Ed

 

[UrsusMaximus]

There are now more than 300 tutorials listed at
www.awaretek.com/tutorials.html so one could even imagine a
"mega-tutorial" using the best-of-breed tutorial for each sub-section,
a la Turbogears ;-)))

Of course it might bear an unholy resemblance to a FrankenTutorial
;-)))

Ron Stephens

 

[AdSR]

I think you guys are up to something. We need some way to aggregate,
update, and extend not just tutorials but all kinds of informatory
material on Python. The Python Wiki is a good place for all that,
although it hasn't become anything resembling a Wikipedia so far.

AdSR

 

[Magnus Lycka]

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?

 

[Steve Holden]

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.

You and me both!

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.

As with all such content, the first thing you will need is a band of
volunteers dedicated to keeping the content up to date, both proactively
and in response to reader comments.

This is a far from easy step.

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.

Yes, I think many people would agree that the existing tutorial is a
little slanted towards people who are already familiar with programming,
and sometimes programming in the Linux/Unix environment.

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.

That's exactly what it's supposed to be: guidance for implementers.

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.

What we are talking about here is a Python Language Users' Guide.

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?

Google are very active supporters of Python already, though they don't
make a big song and dance about it. You might notice, for example, that
they are a Platinum Sponsor at PyCon this year, as well as being a
sponsor member of the PSF. The Summer of Code also benefited Python in
several ways.

There are older-established companies with more Python programmers who
have made hardly any community contribution - the "takers" of the open
source world. I wouldn't like Google to think that the Python community
isn't recognizing their support.

You might also like to ask Alex what he'd feel about losing the
"Nutshell" revenue stream!

regards
Steve

 

[Magnus Lycka]

There are now more than 300 tutorials listed at
www.awaretek.com/tutorials.html so one could even imagine a
"mega-tutorial" using the best-of-breed tutorial for each sub-section,
a la Turbogears ;-)))

We certainly don't need 300 tutorials. Pick the best in the
most relevant categories and promote them to official status.
In a way this is obviously like Turbo Gears... Pick the best
ones and package them together. I don't think we need a lot
of categories though. I think we should be conservative in
what we officially promote, and leave the pointers to various
special interests to the wiki. Perhaps one tutorial official
is enough? In that case it should be Swaroop's. That's the
core language tutorial. Mark's is more a series of visits to
the great land of Python applications, and

That's what I'm proposing. I looked at a few of the beginners
tutorials in the list above. Some are pretty old, others are
present a really bad introduction to Python, showing poor
coding style and a poor understanding of Python.

The current official tutorial isn't ideal for beginners without
previous programming experience, and providing a big bunch of
links for beginners to wade through (as in
http://wiki.python.org/moin/BeginnersGuide ) is far from ideal.
There are more than 40 links on that page for the beginners to
ponder over, and if they decide to follow the
BeginnersGuide/NonProgrammers link, they find another 20+ links.

These 60+ links are more or less equally prominent. There is
no "Go *HERE* first. If you have special interests, you might
want to look at something in this list of other resources as
well".

I'm pretty sure it hadn't looked like this if the official
tutorial had been good enough.

Somehow, the state of Python tutorials remind me of Python
web application toolkits...

I think that one good indication that a tutorial is good,
is that it's been translated to other languages. The ones
I know have been translated are Swaroop's, Mark Pilgrims,
Alan Gaulds, and Danny Yoo's Idle tutorial. Out of these,
Swaroop's and Pilgrim's are the "proper" Python Tutorials.
Danny's is an intro to Idle (which is a good thing) and
Alan's is really more focussed on programing in general
than on Python, although Python is the main vehicle.
(Just like How to Think Like a Computer Scientist.)

 

[A.M. Kuchling]

What we are talking about here is a Python Language Users' Guide.

I actually started on such a document over the holidays, but have only
described about 3 or 4 statements at this point. However, it's
probably not going to be *much* smaller than the Reference Guide,
because pretty much every topic in the RefGuide needs to appear in the
user's guide.

--amk

 

[Magnus Lycka]

Magnus Lycka wrote:
As with all such content, the first thing you will need is a band of
volunteers dedicated to keeping the content up to date, both proactively
and in response to reader comments.

That's why I suggested these already written tutorials. Both
authors have shown that they can make an effort, and there are
other people who have helped with contributions such as
translations. Hopefully, giving these texts a more official
status will stimulate them further and make more people
interested, but I guess it could also go the other way, if it
isn't handled well.

What we are talking about here is a Python Language Users' Guide.
Agreed.

Google are very active supporters of Python already, though they don't
make a big song and dance about it. You might notice, for example, that
they are a Platinum Sponsor at PyCon this year, as well as being a
sponsor member of the PSF. The Summer of Code also benefited Python in
several ways.

I didn't notice the PyCon sponsorship. Maybe that's something for
the EuroPython arrangers to think about... After all, EuroPython 2006
will be at CERN, and that's where the whole web thingie started...

There are older-established companies with more Python programmers who
have made hardly any community contribution - the "takers" of the open
source world. I wouldn't like Google to think that the Python community
isn't recognizing their support.

It has improved lately, and I agree that others could chip in as well.

You might also like to ask Alex what he'd feel about losing the
"Nutshell" revenue stream!

Well, I suggested they'd pay him for it. Perhaps a decent sized sack
of money now is as good as that long term stream... It was just a wild
idea though. You know, they don't usually come true, but who knows?
Suggesting it might increase the chances. It would certainly be a
boost for Python to have such excellent documentation on the web. It
would probably make it easier for Google (and you other big corps!)
to find good Python programmers in the future.

 

[Magnus Lycka]

I actually started on such a document over the holidays, but have only
described about 3 or 4 statements at this point.

Great! I hope you'll find the time to make this into something useful.
I don't know how easy it is to make such a thing into a collaborative
effort. Either way, I think some kind of champion is needed... I hope
we'll see some kind of tools for on-line collaboration for python.org
soon, whether it's something wiki-like or some other way to add comments
to the web pages.

 

[JW]

Here's my two cents -

I started with the official tutorial. It seemed up to date to me.
Things that changed from 2.4 to 2.5 changed in the tutorial as well. I
still refer to it every few days, because it had been a useful
reference for the basic data types. I like that it seemlessly links
into the other documents, both online and in the local MS Help format.
It took a couple of days to get through, and gave me enough of an
introduction to the library that I could get started on the Python
Challenge. I don't think it's broken enough to throw away completely.
Bug reports filed at sf.net appear to be responded to quickly.

I haven't tried "A Byte of Python", so I can't comment.

I tried to learn from "Dive into Python", but I found that it went too
quickly. I have a lot of C and C++ experience, but I needed the more
basic stuff, like dictionaries, tuples, etc. explained in more detail.
It was a very useful guide once I had the basics, but after my initial
experience with it I put Python away for a few months.

"Dive into Python" is not being kept up to date. The last revision was
May 2004, and several things have changed since then. For instance,
chapter 4, on introspection, creates a program called apihelper.py,
which uses introspection and doc strings to print the usage of an
object. This is all great stuff, which would be part of my toolkit,
except that there is a built-in, help(), that does the same thing. I
had to go to the downloaded source to find that out. In other cases,
the tutorial still teaches to older versions of Python, sometimes with
notes for the newer styles, sometimes without.

Another downside is the use of internet sources for examples. For
instance, his example for a web feed is
http://diveintomark.org/xml/atom.xml, which replies with a "410 Gone".
As you might guess, this was the author's server, and might have been
removed because of all the people taking the tutorial. This would have
to be fixed, to make chapters 11 and 12 make much sense.

As for a wiki version of the tutorial, I think the MoinMoin docs are a
good example. MoinMoin is a wiki engine running Python, and the
documents are distributed with each engine. These documents can be
seen on the project website,
http://moinmoin.wikiwikiweb.de/HelpContents. There is a second wiki at
http://moinmaster.wikiwikiweb.de/HelpContents , which contains the
"master" documents. Those that want to help improve, correct, or
translate documents do their work on this wiki. It lowers the number
of pages that maintainers have to review, so that a consistant quality
can be maintained. It also is a (slight) barrier to entry, so that
casual users don't make random changes.

I think the most important thing for a tutorial is a consistant style
and a consistant idea of the user's capabilities. This is easiest with
a single maintainer, but requires constant dilligence and a subdued ego
for a collaborative document.

 

[Magnus Lycka]

I started with the official tutorial. It seemed up to date to me.
Things that changed from 2.4 to 2.5 changed in the tutorial as well.

Agreed. I mainly felt that A Byte of Python seems to go through
the features in Python in a more systematic way. The official
tutorial is being kept up to date concerning details, but it's
basically the same text as ten years ago. I think we owe a lot
of gratitude to Fred Drake and all the other peope who have put
a lot of efforts into the tutorial, but it's too much to expect
that they would transform it significantly. It was written a
long time ago, with different users, use cases and features in
mind.

If we would really get a user guide, I guess there is less reason
to have a differently organized tutorial though. Today, I guess we
suffer from the fact that the tutorial is the only place to describe
things that don't fit in the library reference in a user-oriented
way. Yet, the tutorial is not organized as a reference, and from
the purely tutorial point of view, it wouldn't have to be complete.

I haven't tried "A Byte of Python", so I can't comment.

Please do. I've been programming Python since 1996, so I'm
really just guessing when I try to judge material for beginners.
My impression is that it's aa good and well organized tutorial.

I tried to learn from "Dive into Python", but I found that it went too
quickly.

Right. I would not suggest replacing the official tutorial
with that. I see it more as a complement.

"Dive into Python" is not being kept up to date. The last revision was
May 2004, and several things have changed since then.

Ok. There are two issues here I guess.

First of all, any official material needs to be kept up
to date, whether it's the old tutorial or a new one. It
might be too much to maintain both A Byte of Python and
one more text if we change tutorial(s).

Secondly, since Dive into Python goes beyond the core of
Python, with dependencies to third party stuff, I guess
it's more costly to maintain.

Perhaps it was a bad suggestion to include that. Thanks
for your feedback.

I think the most important thing for a tutorial is a consistant style
and a consistant idea of the user's capabilities. This is easiest with
a single maintainer, but requires constant dilligence and a subdued ego
for a collaborative document.

On the other hand, one size doesn't fit all. Thus my suggestion
of two texts. With the 60+ links that I mentioned before, I don't
think the current way newbies are guided to tutorials is ideal.
There is too much to choose from and to little guidence for those
who try to figure out where to go. The information is also spread
out too much.

http://python.org/doc/
http://python.org/doc/2.4.2/ ==(?) http://docs.python.org/
http://wiki.python.org/moin/BeginnersGuide + sub pages
http://www.python.org/doc/Intros.html
etc...

If the content in these pages were cleaned up significantly
(it's like the wardrobes at home--we can't keep all that old
stuff just because it isn't broken. Throw out the stuff which
isn't essential) I guess we could have less official stuff
(e.g. just one tutorial) and clear links to the others.

Perhaps a better approach would be that Dive ino Python was
one of a smaller set of external links to tutorials, in a
cleaned up set of web pages. At least, it's not a problem today
that there are too few online Python tutorials on the web.