Rethinking the Python tutorial

Discussion in 'Python' started by Magnus Lycka, Feb 9, 2006.

  1. Magnus Lycka

    Magnus Lycka Guest

    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.
    Magnus Lycka, Feb 9, 2006
    #1
    1. Advertising

  2. Magnus Lycka

    Ed Singleton Guest

    On 09/02/06, Magnus Lycka <> wrote:
    > 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
    Ed Singleton, Feb 10, 2006
    #2
    1. Advertising

  3. Magnus Lycka

    Guest

    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
    , Feb 10, 2006
    #3
  4. Magnus Lycka

    AdSR Guest

    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
    AdSR, Feb 11, 2006
    #4
  5. Magnus Lycka

    Magnus Lycka Guest

    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? :)
    Magnus Lycka, Feb 13, 2006
    #5
  6. Magnus Lycka

    Steve Holden Guest

    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/
    Steve Holden, Feb 13, 2006
    #6
  7. Magnus Lycka

    Magnus Lycka Guest

    wrote:
    > 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.)
    Magnus Lycka, Feb 13, 2006
    #7
  8. On Mon, 13 Feb 2006 11:03:55 -0500,
    Steve Holden <> wrote:
    > 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
    A.M. Kuchling, Feb 13, 2006
    #8
  9. Magnus Lycka

    Magnus Lycka Guest

    Steve Holden wrote:
    > 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, Feb 13, 2006
    #9
  10. Magnus Lycka

    Magnus Lycka Guest

    A.M. Kuchling wrote:
    > On Mon, 13 Feb 2006 11:03:55 -0500,
    > Steve Holden <> wrote:
    >>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.


    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.
    Magnus Lycka, Feb 14, 2006
    #10
  11. Magnus Lycka

    JW Guest

    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.
    JW, Feb 14, 2006
    #11
  12. Magnus Lycka

    Magnus Lycka Guest

    JW wrote:
    > 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.
    Magnus Lycka, Feb 15, 2006
    #12
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. stork
    Replies:
    6
    Views:
    341
    Michael Ashton
    Dec 18, 2006
  2. dorayme
    Replies:
    0
    Views:
    370
    dorayme
    May 4, 2008
  3. Steven D'Aprano
    Replies:
    138
    Views:
    1,931
  4. James Edward Gray II

    Rethinking Memoization

    James Edward Gray II, Jan 24, 2006, in forum: Ruby
    Replies:
    8
    Views:
    146
    Robert Klemme
    Jan 27, 2006
  5. John Carter
    Replies:
    3
    Views:
    457
    Robert Klemme
    Mar 30, 2007
Loading...

Share This Page