Documentation suggestions

[Ian Bicking]

Aahz wrote:
> Here's a question that kind of gets to the heart of a lot of the
> problem: where does ``print`` get documented?  If we can come up with a
> good process for answering that question, we can probably fix a lot of
> other problems.  (Note emphasis on the word "process".)

Good point; the language reference and the tutorial is the only place
we currently keep this kind of documentation, and neither provides the
kind of reference that new users need.  I'd also note that the
distinction between builtins and syntax isn't meaningful to a new user.
 So, for instance, that "exec" and "eval" are documented in very
different places is confusing.  And that the "print" statement and the
"write" method are also differently placed.

I think it would be very useful if there was reference (not just
tutorial) documentation for all the syntax, special semantics like
magic methods, and all the functions and objects in builtins.  To a new
user these are all the same thing.  Even to an experienced users these
are all about the same thing.  I don't think such a document would be
all that long or hard to write.

On a usability note, I'd want every name a user might encounter to show
up in an index or table of contents.  Basically all the keywords, magic
methods, exceptions, builtin functions, builtin types, and at least
somewhere the methods of builtin types should also be available.