Python evolution: Unease

[Skip Montanaro]

    Paul> Care to figure out from the docs how tkinter works?  That's not
    Paul> explained anywhere at all, except in some off-site resources and
    Paul> in some printed books.  Even some language features like class
    Paul> methods and slots are explained only in PEP's and release notes,
    Paul> instead of in the language manual where you'd expect to find them
    Paul> since they're part of the language.

Start writing (or reorganizing).  Folks, this is open source.  I'm sure by
the traffic on the list most people here know how to write.  In the case of
Tkinter, you should probably get the okay of the authors of various external
docs before incorporating them into the Python docs, but note that several
Tkinter-related documents are referenced directly from the Tkinter module
docs:

    Python Tkinter Resources
        The Python Tkinter Topic Guide provides a great deal of information
        on using Tk from Python and links to other sources of information on
        Tk. 

    An Introduction to Tkinter
        Fredrik Lundh's on-line reference material.

    Tkinter reference: a GUI for Python
        On-line reference material.

    Tkinter for JPython
        The Jython interface to Tkinter.

    Python and Tkinter Programming
        The book by John Grayson (ISBN 1-884777-81-3).

This being the Internet and all, it's not clear that referencing external
documentation is somehow worse than incorporating it directly into the
distribution.

As for stuff that exists in PEPs and release notes, they should already all
have the necessary copyright (either they were placed in the public domain
or they are already part of the Python distribution) to allow you do just
check out a CVS tree, make the necessary edits and either check the files
back in or submit a patch to SourceForge.

In the documentation arena, I think more thought should probably be given to
producing online docs that can be directly annotated, thus further reducing
the barrier to more complete documentation (and more updates).  Take a look
at latex2html, propose or implement changes, or just rewrite the damn thing
in Python.  I think latex2html is probably a recurring nightmare for Fred
Drake.

Skip