On Aug 12, 1:27 pm, Raymond Hettinger <pyt...@rcn.com> wrote: (snip) > * Many doc requests come from people just learning the language > (that makes sense because the learning process involves reading > the docs). Unfortunately, a fair number of those requests are > flat-out wrong or represent a profound misunderstanding of the > feature in question. That may be an indicator that the docs > need to be improved...
Yes, if many people have problems with the docs then that must be a *clue* to some underling problem in the way the docs are presented. Whether its from misinfomation, misguidance, or just plain misunderstanding on the reader's part that does not matter. There are problems and we need the feedback from everybody noob-to-pro on how to fix this conundrum. One thing that some naysayers may forget is the fact that these noobs most likely have no idea *how*, *when*, or *where* to voice a complaint so they just move on to the next language or suffer with an incomplete understanding of the language and/or proper python idioms. I would say the complaints that this list has seen concerning docs only scratches the surface of the huge underling issues that face us here! > So, if you think eval() is evil (I don't but many > do), we're not going to document that eval() should *never* be used. > If you hate super(), that's too bad -- the docs need to describe > what it does and how it was intended to be used -- the docs are no > place for diatribes on why inheritance is over-used and why you > think the world would be a better place without mixins or > multiple inheritance. Eloquent and beautiful a paragraph that was Raymond. Why, because common sense is just so damn beautiful. Keep the docs clean of personal opinions and just give us the facts people. Who cares about the history of OOP --Google it!-- i want to read about using Python. Give me the nitty-gritty-down-and-dirty-facts that relate to Python syntax and structure, and only the facts, in the most strait forward and common sense way so i can get on to actually writing some code! If you seek self gratification visit c.l.py and vent away, everyone else seems to. -- http://mail.python.org/mailman/listinfo/python-list
