[Doc-SIG] [Python-Dev] Python core documentation

[Fred L. Drake, Jr.]

On Tuesday 06 September 2005 16:26, Rodrigo Bernardo Pimentel wrote:
 >         I sent this to Fred Drake a few weeks ago but got no response. I
 > assume he's busy, or maybe my message never reached him. I hope some of
 > you will have opinions on this (BTW, please Cc: me on any replies, as I am
 > not on python-dev).

Again, I'm sorry I haven't had time to reply until now, but reminders/re-posts 
like this are certainly a welcome reminder!

 >         (Original message below)
 >
 >         I was sharing some ideas with Gustavo Niemeyer (who's also
 > receiving a copy of this message) and he told me you'd be the right person
 > to talk to [he was also the one who recommended that I resent it to
 > python-dev].

I'll suggest that the Documentation SIG is a better place to discuss this for 
some reasons, and I've CC'd that list as well.

 >         I'm relatively new to Python, my first project with it started at
 > the beginning of 2004. And, from the start, its documentation bugged me a
 > little. Now I'm completely hooked and am a full-time Python programmer,
 > but I still see the same quirks in documentation.
 >
 >         I don't mean to say there's lack of it, but I think it needs some
 > work, it seems quite incomplete. I see some of these characteristics in
 > the tutorial and module documentation, but I'm refering mostly to internal
 > documentation.

It appears that by "internal" you're referring to the docstrings available 
from the runtime.  I generally only think of those as hints or reminders, and 
not complete documentation (other minds disagree).  For the non-docstring 
documentation, the same kinds of issues occur, though not always for the same 
features.

I'd categorize the issues you point out into two groups:

A) Omissions.  You're right; there's a lot of places we haven't been as
   thorough as we should be.  These certainly should be corrected by adding
   the missing information.

B) Vague contracts.  There are many places where documentation is omitted
   because the contracts of the documented feature aren't clearly specified
   by the code.  This may happen for many reasons, but how each should be
   handled has to be determined on a case-by-case basis.  In many cases, it's
   intentional that edge cases aren't well specified, simply because the
   treatment hasn't been discussed and decided.

   This case can usually be resolved by bringing up specific cases; once
   there's some discussion, useful documentation can be written because the
   documentation writers learn what the intent was (or the developers have to
   decide what the contract should be).

Historically, I think we've seen a lot of (B) simply because there's an 
expectation of users will read the source to determine what the feature will 
do in any given case.  As we see more implementations appear, and as the size 
and range of Python's audience grow, this becomes a less reasonable approach.  
This is especially the case for features implemented in C, since users are 
increasingly unlikely to have the C sources handy due to the use of 
pre-compiled packages on all platforms.

[...lots of specific examples elided...]

 >         As I told Niemeyer, I considered sending documentation patches,
 > but I think a standard should be defined first, and then volunteers
 > (myself included) could sweep over the core language and conform
 > documentation to it. I'm willing to work on it and help however I can, but
 > I wanted to discuss it first (that's why I came to Niemeyer).

It would be good to have more specific guidelines for documentation.

We've generally avoided trying to specify what exceptions can be raised by 
various functions or methods, and describe only specific cases that are 
guaranteed as part of the API.  Treatment of edge cases is often left as an 
accident as well, though not as frequently.  As the documentation 
increasingly becomes the way that programmers learn about the details of the 
library, we need to think about whether this is the right approach.

In addition to this, we should settle the question of completeness of 
docstrings and document it.  Anything missing that should be included 
according to that decision should then be added.

Also, the level of detail regarding edge cases and exceptions that we're 
willing to make contract should be discussed, and documentation brought up to 
snuff.  This is more likely an issue that will require case-by-case 
treatment.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>