Python documentation too difficult for beginners

[jk]

On Nov 2, 11:49 am, Tim Golden <m... at timgolden.me.uk> wrote:
> 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?

It's not just me who's found the current documentation frustrating.
And sure, the developers know how to code, but they probably can't see
the project with the eyes of a beginner any more.

Making a change to how code is documented to allow more javadoc-style
documentation to be produced could help people migrate from a java
background and ease the learning curve for them, leading to wider
adoption of the language. It wouldn't necessarily mean that the
current documentation style would need to change either.

> In short, please feel free to contribute directly to the core
> documentation effort, or to produce alternatives yourself

I may well do that.

@Tim Wintle
> Personally I use Google, e.g.
> "list site:docs.python.org"
> to bring up documentation about the list type.

Surely you shouldn't have to go to google though? Or the interpreter?
Maybe it's just what you're used to, but I'd expect the language's web
site to provide enough of a reference in itself, while using google
for examples.