Documentation suggestions

[Ian Bicking]

A.M. Kuchling wrote:
> Here are some thoughts on reorganizing Python's documentation, with
> one big suggestion.

Thanks for bringing this up...

> 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.

Since the topic of php.net-style comments comes up often, I thought I'd
note I've been working on a comment system:
http://pythonpaste.org/comment/commentary/ -- this might be useful for
collecting and managing small updates and fixes to the documentation.

> 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.

We don't have a clear place to put that material.  People's personal
pages leave the potential for material disappearing, and since that
stuff usually doesn't have a clear license we can't necessarily be sure
we can move it elsewhere if the original disappears or becomes out of
date.  The Wiki would probably work, and maybe we should just say that
contributions on the Wiki are the preferred form for tutorials and
howtos.  Then, of course, we have to link to them.  With a commenting
system that can happen more organically.

> 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.

There's a lot of dumb modules in there.  I'd love if there was a module
index that excluded modules that were not useful.  Like, say,
MimeWriter or flp.  I think alphabetical or categorized doesn't matter
that much, compared to just a shorter list.  Or maybe categorized, but
layed out so that it still all fits on one screen; the main library ToC
is simply too long because it doesn't fit on a screen, but the
categories can still be useful.

> 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.

Definitely; there's a problem for a newcomer, where the "language" is
documented one place (and hard to find), and the standard library
someplace else.  As a newcomer it can be hard to know which is which.
Also, things like the functions in builtins are particularly hard to
find IMHO.  I usually use pydoc for these things now, but not because I
particularly want to.

> 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 think that an example-based reference could be more useful than the
current layout.  The corner cases *are* important, and it's valuable to
be able to read documentation to fully understand one particular
feature.  Like, say, exceptions (which are undercovered right now).
But it can be easier to understand those with a series of examples
meant to demonstrate the behavior, than with a formal description.

> 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.

A test suite seems far more useful to implementors than any guide,
especially where the accuracy of that guide is not completely assured.
A series of examples seems more concrete than a formal description, and
as such can be not just more helpful, but also a more accurate in how
it transfers knowledge.