Please Contribute Python Documentation!

[Skip Montanaro]

I'm changing the subject so that hopefully people who have long ago tuned
out the "Python evolution: Unease" subject will read this note.

    John> I would like to contribute some documentation to Python.  I've got
    John> the time, I write quite a bit, etc. I've got fairly strong
    John> opinions about some things that need to be documented, (such as
    John> all the new style class descriptor stuff from 2.2) and I have
    John> relatively little difficulty matching the existing style.

    John> However, I don't know TEX, Latex, CVS or Sourceforge. (The latter
    John> two are on my "learn sometime soon so I can put PyFIT where it
    John> belongs" list.)

    John> I have no desire to install Perl to run the documentation
    John> toolchain.  I also have no particular desire to write up a bunch
    John> of final format stuff and drop it on someone else to put into the
    John> latex format so it can be included.

I'm really not picking on John.  I just happen to be replying to his
message.  Others have echoed sentiments similar to his.  Let me emphasize
this.  You do not (repeat, *do not*) need to install any tools to contribute
content to the documentation.  Just whip out your favorite text editor and
type plain old text.  There are plenty of us around who know enough LaTeX to
markup anything you contribute.  Don't let lack of a specific set of tools
be a barrier to contribution!

The preferred way to submit documentation changes is by submitting a patch
to the Python project on SourceForge:

    http://sourceforge.net/projects/python

If you discover an error that requires little more than calling attention to
the problem (or if you don't know how to fix it), just submit a bug report
instead of a patch.  In either case, select "Documentation" as the category.
There is no need to assign it to anyone.  It will get seen shortly.  The
correctness of a documentation fix is generally easier to verify than that
for a code fix, so they tend to get applied pretty quickly.  The only
(small) barrier to submitting bug reports and patches via SourceForge is
that you must register first.  We used to allow anonymous reports but found
that too often they were incomplete and required further input.  With no way
to contact the submitter of an anonymous report we had no choice but to hope
they returned to check for progress.  That only happened rarely, so the
usual resolution was simply to delete the report.

Fred Drake releases new development versions of the docs frequently
(typically once every month or two).  I normally use the development docs
instead of the regular ones for my day-to-day work.  They are available
here:

    http://www.python.org/dev/doc/devel/

It's useful to check to see the most current status of the docs.  The only
thing more current is the source in CVS.

Skip