Python documentation too difficult for beginners

jk sanjo_ie at yahoo.com
Tue Nov 2 14:23:43 CET 2010


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.



More information about the Python-list mailing list