Python documentation too difficult for beginners

[Terry Reedy]

On 11/2/2010 6:42 AM, jk wrote:

> 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).

duh. 'open' is a common word and if you make an unstructured search for 
it in all text, you should get a lot of hits.

The Python docs have both a Global Module Index (which I use constantly) 
and a General Index of functions (methods), classes, and terms. Learn to 
use them. If you look in the [o] section for 'open', the first entry is 
"open() (built-in function)" -- just what you were looking for. There 
are also about 30 more nicely labelled entries for 'open' in various 
modules.

 > 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.

It is possible that this particular entry could be improved.

> Is there much chance that the Python maintainers will change their
> documentation system to make it more like Java or PHP?

There are plans to make doc feedback from users easier.

-- 
Terry Jan Reedy