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

 

[Ben Sizer]

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
(e-mail address removed), 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.

 

[Ian Bicking]

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.

 

[D H]

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.

Yes, do it the way php's documentation is done, Xah Lee's recent trolls
aside.

 

[skip]

Ben> Make the docs like PHP's docs.

Easier said than done. There is still - I think - a project in the works to
redo the python.org website, but I have no idea if it means to retain
ht2html+latex2html as the page builders or move to something else. Neither
ht2html nor latex2html support in inline annotation feature. It would need
to be added.

What was the comment here the other day? Python has more web application
frameworks than keywords. PHP only has one. ;-)

Skip

 

[skip]

Ian> A test suite seems far more useful to implementors than any guide,

Of course, test cases can be modified or ignored. I'd agree with you if we
had a test suite that was more strongly cast in stone.

Skip

 

[Fredrik Lundh]

We don't have a clear place to put that material. People's personal
pages leave the potential for material disappearing

so ? this "if we don't own it, we won't even pretend it exists" attitude
of the PSF is beginning to get a bit boring.

(the standard library suffers from the same problem)

</F>

 

[BartlebyScrivener]

A series of examples seems more concrete than a formal description,<<

Amen. This is why people buy the books: The good ones have lots of
examples. The wizards glance at them in passing and think, "Duh." And
the rest of us (including the intermediate folks, I'll bet) are
grateful for the chance to see a real live example.

rd

 

[Ian Bicking]

so ? this "if we don't own it, we won't even pretend it exists" attitude
of the PSF is beginning to get a bit boring.

Well, I ain't the PSF, so my comment here doesn't really indicate
anything with respect to that. There are already links in the
reference document to external documents. But if we start getting a
half dozen links for each page (which is not an unreasonable number)
the maintenance of trimming dead links and pages that are out of date
becomes more significant. And there's no particular coordination, or
any simple feedback process that can be applied to all content.

I don't think there should be any policy discouraging external links;
there's a lot of sources like the Python Cookbook, some free online
books (e.g., Dive Into Python, or Think Like A Computer Scientist), and
stable personal pages that should be linked in . But I do think that
we should encourage some specific process for new or revised
tutorial/howto contributions, like encouraging people put such material
in the wiki.

Ian

 

[skip]

rd> Amen. This is why people buy the books: The good ones have lots of
rd> examples. The wizards glance at them in passing and think, "Duh."
rd> And the rest of us (including the intermediate folks, I'll bet) are
rd> grateful for the chance to see a real live example.

ISTR that comment was made in reference to the Language Reference, which as
written is intended for "language lawyers". Examples there seem
counterproductive.

Skip

 

[A.M. Kuchling]

stable personal pages that should be linked in . But I do think that
we should encourage some specific process for new or revised
tutorial/howto contributions, like encouraging people put such material
in the wiki.

To this end, I've moved the howtos off their separate SourceForge
project, and into Doc/howto in Python SVN. The sorting howto seemed
small enough and incomplete enough that it would be better as a wiki.
There's another small one, doanddont.tex, that might also be good as a
wiki page. I'm currently not planning to convert any of the larger
documents, such as the curses or regex ones, to wiki format.

--amk

 

[Carl Friedrich Bolz]

Ian> A test suite seems far more useful to implementors than any guide,

Of course, test cases can be modified or ignored. I'd agree with you if we
had a test suite that was more strongly cast in stone.

hum. a test suite like that would have to be constructed very carefully.
The current CPython testsuite tests quite some things that are obviously
implementation details. For example test_itertools.py checks that izip
reuses tuples (which means changing them) when the refcount is 1. This
is something which does not quite work in an implementation using a
different GC

Although on the other hand a short poll revealed that the reference
manual was not considered to be the most useful source among the PyPy
developpers

Cheers,

Carl Friedrich Bolz

 

[Aahz]

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.

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

 

[skip]

Carl> hum. a test suite like that would have to be constructed very
Carl> carefully. The current CPython testsuite tests quite some things
Carl> that are obviously implementation details.

No disagreement there. The current CPython test suite would not cut the
mustard as a test for Python specification compliance.

Skip

 

[Colin J. Williams]

hum. a test suite like that would have to be constructed very carefully.
The current CPython testsuite tests quite some things that are obviously
implementation details. For example test_itertools.py checks that izip
reuses tuples (which means changing them) when the refcount is 1. This
is something which does not quite work in an implementation using a
different GC

Although on the other hand a short poll revealed that the reference
manual was not considered to be the most useful source among the PyPy
developpers

True, but the choice is between abandoning it or updating it.

I would vote for the latter.

Colin W.

 

[Ian Bicking]

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.

 

[skip]

Ian> I think it would be very useful if there was reference (not just
Ian> tutorial) documentation for all the syntax, special semantics like
Ian> magic methods, and all the functions and objects in builtins.

It's pretty common to have a User's Guide as well as a Reference Manual for
many applications. Python has always lacked a User's Guide.

I find it hard to imagine any one person having the time to simply sit down
and bat out such a tome though. I'm partial to using wikis as collaborative
environments. (They more readily admit a group of people to the process
without a formal registration process as would doing the whole thing via
Python's svn repository.) Creating a UsersGuide section of the Python wiki
with reST as the markup might be a good place to work on such a beast with
the goal that it would be a stepping stone to a more standalone document.

Skip

 

[rurpy]

Ian> I think it would be very useful if there was reference (not just
Ian> tutorial) documentation for all the syntax, special semantics like
Ian> magic methods, and all the functions and objects in builtins.

It's pretty common to have a User's Guide as well as a Reference Manual for
many applications. Python has always lacked a User's Guide.

I find it hard to imagine any one person having the time to simply sit down
and bat out such a tome though. I'm partial to using wikis as collaborative
environments. (They more readily admit a group of people to the process
without a formal registration process as would doing the whole thing via
Python's svn repository.) Creating a UsersGuide section of the Python wiki
with reST as the markup might be a good place to work on such a beast with
the goal that it would be a stepping stone to a more standalone document.

Skip

Most of the issues regarding issues like where to "print" and
"sys.write", etc results from a wrong assumtion: that the
Lang ref as only for "language lawyers". My sense is the
many people see the Lang ref as a Syntax manual. It doesn't
have to be only that.

My suggestions:
- Keep the basic organization of the Lang Ref the same
but make the entries more accessible to people new to
Python. If is a reference, keep the BNF, details, etc.
Add (brief, terse!) explanatory material where confusion
may occur. Add examples!! (not 1 in 10000 writers can
write clearly enough to do without examples)

- Move Section 2 (builtin types) from the Lib Ref to the
Lang Ref. This section documents data types, builtin
objects, methods, etc. These are all language things,
not library things.

- Distinction between Lib and Lang is easy: if you import
it, it goes in Lib. otherwise it's in Lang. (If it ain't got ints,
string, None, etc, it ain't the python language. It could be
python without pprint.)

- Make an exception for sys (document in both, or maybe
full doc in Lib, enough doc in Lang to support the needed
references in Lang, or maybe all in Lang as an exception?)

If the Lang ref is made a ref for the language, the
Lib ref for the library, make them both accessible, then
they both get used as they should.

To me, the difference between tutorial and reference is:
Organization:
+ Ref: organised depth-first. Each topic is treated fully
(in complete depth) before the next.
+ Tut: organised breadth-first: broad sweeps are made
accross the subject matter, then again a greater death,
then again, etc.
Audience:
+ Ref: material in a section can assume knowlage level
determined by the material. (description of metaclass
stuff can assume user knows basics of class stuff.)
+ Tut: Knowlage level assumed depends on material's
position in the doc (assumes knowlage of previously
presented material.)
Purpose:
+ Tut: Teach the language to a user.
+ Ref: Allow the user to find out information about the language
Style:
+ Tut: Often chatty: "Now that we've seen how iterators
work, lets put that to work"
+ Ref: Terse: "examples:" (but not TOO terse. Idea is to
transfer info to reader as effectively a possible. If it takes
reader (of the assumed level) 5 minutes of thinking to
say "oh, now I see" something's wrong.)

Both tutorial material and reference material are desirable but
if resources allow only one reference is better.

A user guide would be great but just an update of the tutorial
and some reorganiztion and expansion of the two primary
references would improve things a lot in the interim.

(sorry for the rough shape this posting is but I've got to run.)

 

[BartlebyScrivener]

You are correct about the tutorial. Just try to look at the home page
through the eyes of a curious Windows user who wants to learn
programming and is trying to decide whether to take up Perl, Ruby,
Python, or Visual Basic, let's say.

On the home page, the first link that catches the eye for this user is:
"Beginner's Guide to Programming - <bold> start here if you're new to
programming </bold>." That's me. Click.

Now you are on a page with promising-looking links that all start with
"BeginnersGuide," but the first three are not warm welcomes, they are
housekeeping matters about where you can take courses or how to
download Python for people who don't know whether they want to or not
yet, or there's one that says "examples" which will take you to the
ActiveState Cookbook site so you can get really confused.

Then you hit the link that says "BeginnersGuide/Nonprogrammers" Ah!
That's me. <click>

The first prominent link says: "Python Tutorial" along with a notice at
the top of the page that tells you if you've never programmed before
this is the page for you.

Click on Python Tutorial. Some official business to start off. Then you
see, "Whetting Your Appetite" Ah, I am ready for that. <click>

The first sentence reads:

"If you ever wrote a large shell script, you probably know this
feeling: you'd love to add yet another feature, but it's already so
slow, and so big, and so complicated; or the feature involves a system
call or other function that is only accessible from C ...Usually the
problem at hand isn't serious enough to warrant rewriting the script in
C; perhaps the problem requires variable-length strings or other data
types (like sorted lists of file names) that are easy in the shell but
lots of work to implement in C, or perhaps you're not sufficiently
familiar with C."

Most of the site has been laid out by programmers, for programmers, who
apparently want to keep it that way, based upon what I've seen.

 

[Peter Hansen]

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

Sometimes a poor or missing process can be supplemented with improved
technology. If the prospective audience can always answer the question
"where _was_ ``print`` documented?" it would somewhat lessen the
importance of having said good process.

I mention this (admittedly obvious) point only because (a) sometimes
debates about process are fruitless, and (b) having _both_ would fix
even more problems than just having a good process.

-Peter