Python docs disappointing
Martin P. Hellwig
martin.hellwig at dcuktec.org
Sat Aug 1 02:14:33 CEST 2009
<cut python has poor documentation explanation>
Well to a level I agree with you.
If you are totally new to programming
you won't/can't invest in educational material
have an adversity for looking up resources using a web browser
_and_ don't have the patience for trial and error
getting proficient with the language is almost impossible.
Sometimes some modules are completely incomprehensible for me and that
is after I have looked at the docstrings, the python doc and examples
found using Google. However usually after combining all three with a
fair bit of experimenting I figure it out, to me that is fun I like that
kind of puzzles but I am aware that this isn't the best possible situation.
Overall I would say a better situation would be if the standard python
documentation would have an *extensive* 'pattern' section for each
module much like, for example, Frederik Lundh did this with his tkinter
documentation. Incorporating these patterns in the standard
documentation would save you some jumping around sites and it is perhaps
more 'trustworthy' coming from the source (pun intended).
I believe that the documentation is all ReST format, so there should be
a way (if there isn't already) to display the extensive documentation
from the interpreter directly for the module you are working with. As
you probably noticed, I actually never bothered to look if this isn't
already the case. Which is a good indication to how much it has actually
Furthermore I like to add to my reply, which is already longer then I
anticipated at first, the thing I don't agree with you is the following
(and comparative in nature): Compared to all other 'popular' languages I
find Python actually very, very good documented and if you can't learn
Python using the available documentation and on-line resources I think
it is unlikely you can learn any other language, whether this is a
programming language or a natural language. Actually, I should have
replaced 'any' with 'anything' followed by a full stop.
'If consumed, best digested with added seasoning to own preference.'
More information about the Python-list