Python documentation too difficult for beginners

[AD.]

On Nov 3, 7:43 am, Tim Harig <user... at ilthio.net> wrote:
> On 2010-11-02, jk <sanjo... at yahoo.com> wrote:
>
> > As for the 9 paragraphs statement, there's a usability book that
> > applies here - it's called "Don't make me think". I shouldn't have to
>
> Anything that promotes a lack of thinking sends up red flags in my head.
> We want to recruit smart people who think, not idiots.

"Don't make me think" is the UI equivalent of "There should be one and
preferably only one obvious way to do it". Not about advocating no
thinking, but about reducing the amount of unimportant decisions you
require your users to make. But I don't think the book specifically
addresses Dutch users though.

Back on topic - I do like the Python docs overall. Especially compared
to the PHP docs. I like the overall look and format of the new Sphinx
generated ones too.

My only criticism is that the content can sometimes be a little too
terse/concise. It's fine for experienced developers, but in some
places a little more explanation and/or examples would help out the
less experienced. I can usually figure out how to do something
eventually, but the docs for some modules take more deciphering than
others.

--
Cheers
Anton