Python documentation too difficult for beginners

[jk]

Hi,

I've been coding in PHP and Java for years, and their documentation is
concise, well structured and easy to scan.

Others have mentioned this apparently for years (see:
http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851
and http://www.russellbeattie.com/blog/python-library-docs-still-suck
and http://xahlee.org/perl-python/xlali_skami_cukta.html).

Compare for instance the differences in ease of use, and speed of use,
of these:

http://docs.python.org/library/functions.html#open
http://uk.php.net/manual/en/function.fopen.php

The former is difficult to find (try searching for 'open' in the
search box and see what you get). It is simply a collection of
paragraphs without strong enough contrast to differentiate the
different parts - parameters, parameter values, return types,
exceptions and related functions. It is slow to read and doesn't allow
easy visual scanning.

The latter has clearly delineated, standardised content areas for each
of these without excessive text. It uses tables which are easy to scan
for possible opening modes and allows users to contribute their own
examples.

Sadly, the use of restructured text by python doesn't allow a new
document generator to be written - all existing documentation would
need updating with docblocks or something similar.

Has anyone else struggled while trying to learn the language? The
whole documentation system seems geared towards people who already
know what they're looking for and is close to useless for beginners.
I'm not the only one who finds google an easier way to find
documentation about python.

Is there much chance that the Python maintainers will change their
documentation system to make it more like Java or PHP? How would I go
about trying to make that happen?