"Tony Meyer" <[EMAIL PROTECTED]> wrote: > > But, the standard responce of "don't complain, fix it yourself" is > > bogus too. There are plenty of people on this list willing to sing > > python's > > praises, for balance, there should be people willing to openly > > point out > > python's flaws. > > This makes no sense. If you want to complain about Python, try a > Perl list. Why would a list dedicated to discussion about/help with > a language need complaints about the language?
1. So group readers might have advance warning of problem they may run into. 2. To give potential adopters of Python a more even handed view of the language. 2. So developers will have a better idea of the problems the user base is actually having with Python. 3. To motivate those who are looking for a way to contribute. 3. So that people who want to express an honest opinion in an open forum won't feel intimidated. I could probably think of more but I'm tired of typing. I propose a couple additions the Zen document: Reality beats fantasy. Open discussion is better that propaganda. > You might want to consider the difference between complaining and > constructive criticism and suggestions, and which are likely to get > better responses. I agree within limits, but sometimes "constructive criticism" means "play by our rules" which for me is outside the limits. Also non-constructive criticism while not as valuable, is not worthless either. > > Documentation is certainly one of them. > > FWIW, I have found Python's documentation to generally be excellent. FWIW I find Python's docs to be OK at best, with some horrible parts, and a lot of mediochre to poor parts. 1. I have seen recommendations here to use new-style classes. I believe classes are at the core of Python, the entire language is built around and rests on them. Yet, unless I missed it, new style classes are almost completely undocumented in the Language Reference Manual. This alone is sufficient to condemn the documentation. 2.Section 2 of the Library Reference should clearly be in the Language Reference manual. 3.There are way to few examples in the docs. 4.There are way to few cross references in the docs (for example the datetime module doesn't even mention the existence of the time" module.) [I double checked before posting and see this is no longer true, but I think it is still true in many other cases. ] 5.Forward refernces (mention of things explained or defined later in the manual) are seldom identified as such. They should be a link to the appropriate part of the manual. 6.There is often no notational distinction for terms used in a general sense and a python specific technical sense leading to confusion. 7.The writing is often too terse. (To parapharse, it should be as terse as possible but no terser. I think it often violates the that last clause.) 8.There is critical missing info. (I lost many hours once because the process module (or popen? I forgot) failed to document it didn't do unicode.) 9.Many other small details, e.g is it neccesary for the one of the most frequently used datatypes (string) to not appear in the table of contents? (That's not retorical, I really don't know. Maybe it is, but if things could be arranged to that it did, it would be better.) > > And I was correcting a posting that explicitly said there was > > exceptionaly > > good information in that Howto. That was just plain wrong. > > It is exceptionally good information. The version that was at that > link is somewhat dated (but still excellent for anyone using older > versions of Python, or for those that need to remain compatible with > older versions, and there are a lot of those people around), but the > updated version is also excellent. I'm sure amk will either update > his page to point to the new one or update the content at some point. No, it is not exceptionally good information. It is outdated information, it does not say it is outdated, and it will lead to poor practice when used in the version of Python that it documents. That clearly makes it "not good". > The point is that you're much more likely to improve things if you > politely point out a problem and suggest a solution than simply make > a complaint. I did. As for my original responce I think the suggestion was clear if implicit: stop referring to outdated documentation as a "treasure". The suggestion in my "update the damn docs" comment was quite explicit I think. -- http://mail.python.org/mailman/listinfo/python-list