Re: Rethinking the Python tutorial
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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
A.M. Kuchling wrote: On Mon, 13 Feb 2006 11:03:55 -0500, Steve Holden [EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
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? :) -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
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/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
On Mon, 13 Feb 2006 11:03:55 -0500, Steve Holden [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
[EMAIL PROTECTED] 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.) -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
On 09/02/06, Magnus Lycka [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list
Re: Rethinking the Python tutorial
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 -- http://mail.python.org/mailman/listinfo/python-list
Rethinking the Python tutorial
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. -- http://mail.python.org/mailman/listinfo/python-list
