Python documentation too difficult for beginners

[jk]

On Nov 2, 1:42 pm, Steven D'Aprano <st... at REMOVE-THIS-
cybersource.com.au> wrote:
> It's always difficult to know how much information is too much. The PHP
> docs seem to take an "everything including the kitchen sink" approach.
> Given that approach, it makes sense to divide everything into
> subsections, one page per function. But with Python's minimalist
> approach, it would just be annoying. Compare the four lines of:
>
> http://docs.python.org/library/functions.html#id
>
> with this re-write in the PHP fashion:
>
> =====
> id
> =====
> (Python 1.x, Python 2.x, Python 3.x)
>
> id -- id of an object
>
> Description
> -----------
>
> id(object)
>
> id returns the numeric "identity" of an object, which is guaranteed to be
> unique and constant for this object during its lifetime.
>
> Note: two objects with non-overlapping lifetimes may have the same id()
> value.
>
> Note: CPython implementation detail: This is the address of the object.
>
> Parameters
> ----------
>
> * object
>
>   Any object.
>
>   Note: all data in Python are objects, even ints and strings.
>
>   Note: there are no undefined objects in Python. If you call
>   id(variable) on an unbound variable name, Python will raise an
>   exception.
>
> Return values
> -------------
>
> Returns an integer or long integer object representing the ID of the
> argument.
>
> Errors/exceptions
> -----------------
>
> If the argument to id() is a named variable rather than a literal, and
> that name is not bound to any object, then a NameError will be raised.
> Otherwise every call to id() must succeed.
>
> Note: if the call to id() is inside a function, the exception may be a
> subclass of NameError such as UnboundLocalError.
>
> Note: literals are not guaranteed to always refer to the same object.
>
> Changelog
> ---------
>
>   0.9  First version added (I think).
>
> Examples
> --------
>
>    id(x)
>    id(alist[1])
>    id(instance.attribute)
>    id(module.name.attribute['key'].method(arg1, arg2).seq[2])
>
> Notes
> -----
>
>    If you're still reading, I admire your persistence.
>
> See also
> --------
>
>    Python's object model
>    Exceptions
>
> Steven

You're right in that the python docs in this case are less lines, but
that's one of the problems. It doesn't mention anywhere the extra
detail you've added regarding exceptions thrown. That's the kind of
thing that probably comes through experience or some kind of
convention which isn't obvious to beginners. Having things split into
sections - parameters, return types, exceptions, etc - lets me find
what I'm looking for quickly.

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
go through freeform text to find what I'm looking for when a list
would make that information easier to find. And splitting the docs
into sections would allow me to skip to what I'm looking for. I really
would be much happier with your example documentation.

I think the key difference is that I don't want to have to *read* the
python docs - I want to be able to scan for what I'm looking for and
find it easily. That makes me productive.