Python documentation too difficult for beginners

[News123]

On 11/02/2010 02:42 PM, Steven D'Aprano wrote:

> However, there is a Python wiki. It doesn't get anywhere near as much 
> love as it deserves, and (I think) the consensus was that the official 
> Python docs should stay official, but link to the wiki for user-
> contributed content. This hasn't happened yet.
> 
> http://wiki.python.org/moin/


That sounds like an excellent idea.
I often would have appreciated more examples or discussions about a
given module/class/function without having to fall back to Google.


It might be a good compromise:

clearly separating official doc and examples, but accepting, that the
doc is often insufficient without digging into the sources or searching
for more xamples.

The more one uses python, the easier it becomes to find what one looks for.

My first Impression about Python however was:
- the basic language is rather easy to learn
- the library documentation was more difficult to understand than the
one for PHP or for Perl.



> Frankly, I think that the best thing you could do is start a fork of the 
> docs and see if you get any interest from people. If you do, then you can 
> go back to python-dev with proof that there is a genuine popular desire 
> for more structured, PHP-style documentation.

I'd prefer crosslinking the doc with something, that's easier for
beginners of for people who never used a given library before.