Documentation suggestions

[A.M. Kuchling]

Here are some thoughts on reorganizing Python's documentation, with
one big suggestion.

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.

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.

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.  Here I think the solution is to encourage
separate tutorials and HOWTOs, and link to them from the LibRef.

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.

The Extending/Embedding manual isn't great, but only advanced users
will come in contact with it, so I don't think it's a critical factor.
(Michael Hudson's new manual is a promising replacement.)

I suspect the Achilles' heel of the docs is the Language Reference.
Put aside the fact that it's not up to date with new-style classes and
other stuff; that would be fixable with some effort.

To some degree, the guide is trying to be very formal; it's written
like a specification for an implementor, not a document that people
would read through.  But there's no other way for people to learn
about all the special object methods like __add__; the tutorial can't
cover them all, and the LibRef doesn't describe them.  So the newbie
is stuck.

For example, I noticed this passing reference in Tim Bray's weblog:
http://www.tbray.org/ongoing/When/200x/2005/08/27/Ruby

	Based on first impressions and light exposure (a basis that
	matters a lot) Ruby seems better-documented and easier to get
	into than Python. I've actually written (a little)
	production code in Python, but I always had the feeling that
	there was lots of stuff going on I didn't understand; a
	couple of days in, I think I have a better grasp on what
	Ruby's up to, even where I'm not looking.

I don't know exactly what Bray meant, but suspect that a more readable
reference guide would have helped him understand what was going on.

Perhaps we need a friendlier counterpart to the RefGuide, something
like the 20-page introduction to Python at the beginning of Beazley's 
Essential Reference:

	  * go over the statements one-by-one
	  * go over the basic types and their methods
	  * go over object semantics
	  * cover some of the lexical material in chapter 2 of the RefGuide
	  * overarching principles: go into a fair bit of detail, but
	    not every corner case; make the text readable, not meticulously 
	    precise.

(I should point out: this suggestion is not entirely different from
some of the suggestions that X*h L** has made.  He (?) makes his
suggestions in a venomous style, and with his own eccentric
terminology, but that doesn't mean he's always wrong, e.g. his
complaints about the re module's documentation are well-placed in the
main.)

One problem with such a friendly document: it might make the Ref Guide
even more irrelevant, if we always updated the friendly document
(which is easy) and left the RefGuide to drift even further out of
date (because it's hard to update).  I don't know if this is an
argument for not having a friendly guide, or for dumping the RefGuide
entirely.

Dumping the RefGuide means there isn't a more formal-style description
of Python's semantics.  I don't know if this matters.  In theory, the
implementors of Jython or IronPython could be using the RefGuide to
know what they need to implement, but in practice I suspect
implementors use the test suite and existing library as checks.  Maybe
we don't really need a tediously precise description of Python.

What do people think?  

--amk