Python documentation too difficult for beginners

[Tim Golden]

On 02/11/2010 11:23, jk wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
>
> Why aren't the official docs like this, and why has it taken me 2 days
> of searching? All this needs is a search engine behind it and it'd be
> perfect.

I'm glad you find the epydoc format useful. And I'm glad that various
people have taken the trouble to produce documentation for Python in
various formats that suit them. But why do you imagine that the core
Python documentation -- developed and maintained by a group of people
who clearly have some idea what they're doing -- should change to a
format which happens to suit you?

The Python documentation source and the source code of Python itself
are all freely available. Any initiative by you or by others to
produce alternative, possibly searchable and commentable, versions of
them would I'm sure be welcomed by many. But not everyone finds, eg,
the PHP style of user annotation helpful. Not everyone likes epydoc
output: I don't myself.

In short, please feel free to contribute directly to the core
documentation effort, or to produce alternatives yourself and to
advertise them here or elsewhere within the Python community. But
please don't come along and say "Why aren't the Python docs like
<this other thing> which happens to suit me better?"

TJG