Python Documentation Blows!

[Ed Cogburn]

Peter Hansen wrote:
> anton muhin wrote:
> 
>> Maybe just start a wiki based on the current documentation? It 
>> shouldn't be too difficult, should it?
> 
> 
> What part of http://wiki.wxpython.org/ is not adequate?  ;-)


The poster is referring to Python, not wxPython.  I like the idea myself very 
much.  My biggest problem with the official Python docs, is that there is too 
much space wasted on formal definitions and not enough space on actual 
examples using valid code.  To anyone without a complete and formal CS 
education, the use of the formal syntax to specify Python's syntax amounts to 
describing one new language using another new language - not exactly helpful. 
  :) An 8 to 10 line example is worth a page of BNF (or whatever), IMO, and 
the difference is that the simple but real-world example works just as well 
for the CS graduate as it does for the hobbyist programmer.  A wiki site for 
this would have meant I could have provided some example code for the things I 
had trouble with, once I figured them out myself, it would at least make it 
easier for a lot more people to participate on the creation of Python's docs. 
  I like Python very much, but the truth is, had it not been for the 2 
third-party books on Python that I have (Bible and Complete Reference), I 
might not be using Python now.