Rethinking the Python tutorial

[Steve Holden]

Magnus Lycka wrote:
> 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.
> 
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
-- 
Steve Holden       +44 150 684 7255  +1 800 494 3119
Holden Web LLC                     www.holdenweb.com
PyCon TX 2006                  www.python.org/pycon/