Python documentation too difficult for beginners

Tue Nov 2 09:42:17 EDT 2010

On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote:

> Hi,
> 
> I've been coding in PHP and Java for years, and their documentation is
> concise, well structured and easy to scan.

Well, that's one opinion.

> Others have mentioned this apparently for years (see:
> http://stackoverflow.com/questions/4046166/easy-to-navigate-online-
python-reference-manual/4070851
> and http://www.russellbeattie.com/blog/python-library-docs-still-suck
> and http://xahlee.org/perl-python/xlali_skami_cukta.html).
> 
> Compare for instance the differences in ease of use, and speed of use,
> of these:
> 
> http://docs.python.org/library/functions.html#open
> http://uk.php.net/manual/en/function.fopen.php
> 
> The former is difficult to find (try searching for 'open' in the search
> box and see what you get).

A fair point -- the built-in open comes up as hit #30, whereas searching 
for open in the PHP page brings up fopen as hit #1. But the PHP search 
also brings up many, many hits -- ten pages worth.

But in any case, the Python search functionality could be smarter. If I 
had a complaint about the docs, that would be it. Fortunately, I have 
google :)

> It is simply a collection of paragraphs
> without strong enough contrast to differentiate the different parts -
> parameters, parameter values, return types, exceptions and related
> functions. It is slow to read and doesn't allow easy visual scanning.

It's *nine* paragraphs, three of which are one-liners, the longest of 
which is eight lines. If you have trouble reading that, well, you have a 
problem. The PHP docs for fopen are FIFTY-EIGHT paragraphs.

Okay, okay, I was unfair. I counted section headings as separate 
paragraphs. A more reasonable count is... twenty-six paragraphs, tables, 
sections and subsections. Plus *dozens* of user-contributed recipes, bug 
reports, tricks, tips and comments. And you call this concise???

Reading the docs, I'd say that PHP needs all this extra documentation 
because it's so much more complicated. fopen has all this implicit magic 
behaviour that needs documenting -- it will try to guess a scheme from 
the file name, if it can't guess the scheme it will guess that it's a 
local file, and the behaviour depends on various globals. In comparison, 
Python's open is very simple: it only opens files. No wonder Python's 
docs are simpler.

The PHP docs felt it necessary to give a warning *three times*, one after 
the other, about using binary mode when opening files. Apparently once 
was not enough.

The Description subsection of the PHP fopen doc says:

    fopen() binds a named resource, specified by filename, to a stream.

What's a stream? So I read, and read, and read, and eventually, almost at 
the bottom of the official docs, I find the section "Return Values":

    Returns a file pointer resource on success, or FALSE on error.

Great! Now, what's a file pointer resource, and how does it differ from a 
stream? No idea.

Contrast that with the Python docs. In the *very first sentence*, it says:

    Open a file, returning an object of the file type described in
    section File Objects.

with both "file" and "File Objects" being hyperlinks to the appropriate 
part of the docs. I think I'll stick with the Python style, thank you 
very much.

> The latter has clearly delineated, standardised content areas for each
> of these without excessive text. It uses tables which are easy to scan
> for possible opening modes and allows users to contribute their own
> examples.

There has been discussion on python-dev about user contributed examples. 
The pros are that users can add tricks and tips. The cons are that, 
without constant attention, the user-contributed content will grow old 
and stale, or worse, be filled with nonsense.

However, there is a Python wiki. It doesn't get anywhere near as much 
love as it deserves, and (I think) the consensus was that the official 
Python docs should stay official, but link to the wiki for user-
contributed content. This hasn't happened yet.

http://wiki.python.org/moin/

> Sadly, the use of restructured text by python doesn't allow a new
> document generator to be written - all existing documentation would need
> updating with docblocks or something similar.
> 
> Has anyone else struggled while trying to learn the language? The whole
> documentation system seems geared towards people who already know what
> they're looking for and is close to useless for beginners. I'm not the
> only one who finds google an easier way to find documentation about
> python.

Why do you think this is a bad thing? The Python docs are the reference 
manual, not a tutorial. Quite frankly, if I were a PHP developer, I'd be 
pretty annoyed at having to read this in the docs for fopen:

    If you use the wrong line ending characters when writing your
    files, you might find that other applications that open those 
    files will "look funny".

Gosh, really? Thanks for the tip, Captain Obvious.

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

> Is there much chance that the Python maintainers will change their
> documentation system to make it more like Java or PHP? How would I go
> about trying to make that happen?

Unlikely. You could raise the issue on the python-dev list, or see if 
there is a SIG mailing list specifically for the docs.

Frankly, I think that the best thing you could do is start a fork of the 
docs and see if you get any interest from people. If you do, then you can 
go back to python-dev with proof that there is a genuine popular desire 
for more structured, PHP-style documentation.

-- 
Steven