Social problems of Python doc [was Re: Python docs disappointing]

r rt8396 at gmail.com
Wed Aug 12 22:14:51 CEST 2009


On Aug 12, 1:27 pm, Raymond Hettinger <pyt... at 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.



More information about the Python-list mailing list