Python docs disappointing

[Martin P. Hellwig]

kj wrote:
<cut python has poor documentation explanation>

Well to a level I agree with you.

If you are totally new to programming
_and_
you won't/can't invest in educational material
_and_
have an adversity for looking up resources using a web browser
_and_ don't have the patience for trial and error
*then*
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 
bothered me.

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.

-- 
MPH
http://blog.dcuktec.com
'If consumed, best digested with added seasoning to own preference.'