On Nov 6, 2010, at 10:45 AM, D'Arcy J.M. Cain wrote: > On Sat, 6 Nov 2010 10:22:47 -0400 > Philip Semanchuk <phi...@semanchuk.com> wrote: >>> The tutorial isn't meant as an exhaustive lesson on every single Python >>> feature. >> >> I agree, and I don't expect otherwise. My point was that if the >> tutorial doesn't mention a feature, the only other place to learn about >> it (on python.org) is the language ref. Some people might think the >> language ref is a fine place to direct newcomers to Python. I don't. > > I don't think that anyone was suggesting the reference as the first > place to send newcomers.
Hi D'Arcy, I agree, no one -- not even I -- suggested that. The tutorial is always the first stop. > You send them there when they need something > beyond the basics. But IMO this is still a problem. After the tutorial, then what? Someone who has read the tutorial can still be new to Python by my definition. You may feel that the current language ref is OK for newcomers. I don't, and that's my point. > I think the only issue here is that operators are > pretty basic and that specific thing is missing in the tutorial. It > would be a mistake to write a whole new document because the tutorial > is missing one thing. Better would be to propose an operators section. The issue is not just operators. As I mentioned, the tutorial doesn't cover decorators, assert, exec, ternary if, and maybe a few other things. IMO that's fine. A tutorial should introduce the basics. I'm sure we could have a fine argument about what features of Python are basic and which are advanced, but I'd rather not as long as we can agree with Steven D'Aprano's comment that "The tutorial isn't meant as an exhaustive lesson on every single Python feature". I certainly agree with that. Personally, I liked using the tutorial for learning Python. It's readable. But after getting familiar with the language I wanted to move on to something more structured. I also realized that the tutorial didn't cover every aspect of the language because I saw references in code and discussions to things that weren't mentioned in the tutorial. I didn't feel like the python.org documentation provided an obvious next step, though, because I started with Python 2.3, and the language reference was still entitled "for language lawyers" back then. The section's name may have changed since then, but it looks like the style hasn't changed much. I believe the lack of a complete, friendly post-tutorial document to read made learning Python more difficult for me. >> I realize that the Python Foundation doesn't have infinite resources >> to work with, so maybe they'd love to create & maintain a more readable >> language reference if they had time/money/people. I don't hear anyone >> talk about it, though. > > Lots of people talk. Action, not so much. How about you? Are you > ready to start writing a new reference manual? First you suggest that writing a whole new document would be a mistake, then you encourage me to do it. =) The old open source challenge of "If you don't like it, fix it" is liberating but it's also a nifty way of changing the subject. Whether or not I can or will fix a problem doesn't make my criticism any more or less legitimate which (I thought) was the issue at hand. To answer your question: no, I'm not willing to start writing a new reference manual. For one thing, I don't think it's wanted judging by the response I've seen here. I see a lot of people saying "what we have is fine". To put it another way, based on this small sample size survey, opinions are mixed on the current state of the documentation. The effort required to make substantial changes (e.g. create a reference manual that's sort of a marriage of the tutorial and the language spec) is large but would likely result in very little net improvement as perceived by the community as a whole. To put it a fifth way (Sir Galahad: "third, sir") -- people learn differently. Cheers Philip -- http://mail.python.org/mailman/listinfo/python-list
