Documentation suggestions

[Ben Sizer]

A.M. Kuchling wrote:
> The tutorial seems to be in pretty good shape because Raymond
> Hettinger has been keeping it up to date.  It doesn't cover
> everything, but it's a solid introduction, and if people don't find it
> works for them, they have lots of alternative books.  No suggestions
> here.

The last time I looked at it, I thought the tutorial was the weakest
part of the documentation, because it assumed you were coming at Python
from another language, and often assumed that language was C. I mean,
the very first line says, "If you ever wrote a large shell script"...
which most people never have. The second page assumes you're using Unix
and throws in Windows as an afterthought. The third page demonstrates
string literals using the term "just as you would do in C". This is a
bit pointless because anyone familiar with C is probably bright enough
to make the connection for themselves, and anyone who isn't will not
appreciate what is being explained. This sort of theme continues
throughout.

Once upon a time I expect nearly all Python programmers came from C,
but today, I doubt that is true, especially since most universities
seem to prefer teaching Java over C++. In short, the tutorial is quite
outdated for today's prospective Python programmers. Admission: I once
offered to help clean it up, but by the time I got a reply from
docs at python.org, I had started a new job and no longer had time. Sorry.

As for the alternative books comment, I think this is very wrong...
people are surely far more likely to buy a comprehensive reference to a
language they're already hooked on by a good tutorial, than they are to
buy an entry-level text for a language they don't quite understand but
which seems to boast good reference material!

> There are endless minor bugs in the library reference, but that seems
> unavoidable.  It documents many different and shifting modules, and
> what to document is itself a contentious issue, so I don't think the
> stream of small problems will ever cease.

Make the docs like PHP's docs. Users can post addendums and corrections
to the documentation, then all one of the official maintainers has to
do is fold in those corrections later.

> There's another struggle within the LibRef: is it a reference or a
> tutorial?  Does it list methods in alphabetical order so you can look
> them up, or does it list them in a pedagogically useful order?  I
> think it has to be a reference; if each section were to be a tutorial,
> the manual would be huge.

I agree: reference foremost. However, all but the most trivial
libraries should have a short example, preferably on the first page of
their docs, so that you can quickly get an idea of whether this does
what you want it to do, and how the code is going to look. Some
libraries don't (ConfigParser comes to mind, Threading is another)
which make using them a bit of a chore to begin with. Again, if web
users could contribute examples as comments on the docs as with PHP,
they can be added in later.

> The library reference has so many modules that the table of contents
> is very large.  Again, not really a problem that we can fix; splitting
> it up into separate manuals doesn't seem like it would help.

Personally I'd be happy to see a lot of those modules removed from the
distribution, but I expect few will agree with me. ;)

-- 
Ben Sizer