Python evolution: Unease

[Skip Montanaro]

    Paul> Skip Montanaro <skip at pobox.com> writes:
    >> 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.

    Paul> Irrelevant, the issue isn't what docs can be written if someone
    Paul> wants to do it, it's what docs are actually already there.  

How do you think we got the docs we already have?  Somebody wrote them.  If
there aren't enough docs or if they have mistakes, then somebody has to
correct them.  I'm just suggesting that more people put their money where
they mouths are so-to-speak.

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

    Paul> The same thing could be said for software.  So why not eliminate
    Paul> the Python library and let everyone download each module
    Paul> separately?  Because it's bogus is why.
    Paul> It really does matter whether something is included or just
    Paul> referenced.

Okay, then start doing the work necessary to incorporate that stuff into the
core.  Get Fredrik to say "okay" to including his Tkinter docs, then do what
it takes to incorporate it.  The fact that Fredrik can check those docs in
himself but hasn't after several years suggests that he prefers the status
quo for one or more reasons.

I'm not saying references are perfect.  I'm saying that given the time
constraints of the existing developer crowd and the relative priority of
various open tasks that folding in external documentation hasn't risen to
the top of the queue yet.  The best way to make that happen is for it to be
your highest priority and then for you to make it happen.  That's a
longer-winded way to say what I meant with "this is open source".

    Paul> And that was just about Tkinter, for which good docs exist but
    Paul> just don't happen to be in the distro.  How about something like
    Paul> SocketServer, for which no reasonable docs exist at all?  

I'm at a loss.  Is there something about this quote taken directly from the
section of the library reference manual entitled "Undocumented Modules" that
is unclear?

    Here's a quick listing of modules that are currently undocumented, but
    that should be documented.  Feel free to contribute documentation for
    them!  (Send via email to docs at python.org.)

The list there is itself incomplete.

There is a reference manual section for SocketServer, btw:

    http://www.python.org/doc/current/lib/module-SocketServer.html

If that needs examples or corrections or is incomplete, feel free to submit
a patch to either SourceForge or by email to docs at python.org.

    Paul> I'm not trying to bash Python, which is excellent in many ways, or
    Paul> I wouldn't be using it.  I just see various other free software
    Paul> projects as trying to live up to higher standards and I think
    Paul> Python should aspire to the same thing.

I'm sorry, I don't know quite how to respond to that.  Sure, I imagine there
are other communities that do it better.  I've seen PHP mentioned here
recently, and have direct experience with CPAN (and actually like it pretty
well).

Look, I don't have much free time, and what free time I do have I mostly
spend moonlighting on other software (much to my wife's chagrin).  I imagine
most of the other people who contribute to the Python distribution are
similarly time-afflicted.  Here are a couple ideas:

    1.  Do you have more money than time?  Donate a few bucks to the PSF:

            http://www.python.org/psf/

        Someone will probably do #2.

    2.  Do you have more time than money?  Write a proposal to the PSF to
        implement/improve/polish off some aspect of the distribution:

            http://www.python.org/psf/

    3.  Got some free time and don't care about a few extra bucks?  Check
        out how to contribute to Python:

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

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

    Paul> And about that full featured Python web browser and native-code
    Paul> Python compiler, all you have to do is go write it.  Come on.

Where did I say to go write a browser or a native-code Python compiler?  If
that's your bag you can try resurrecting something Grail-like (browser) or
contribute time top PyPy or Psyco.  When I said "write", I literally meant
write, as in English text.

    Paul> Having to piece together info from a dozen obscure and
    Paul> inconsistent PEP's and stuff in the CVS tree and source comments
    Paul> is not what most people think of as "documentation".
    Paul> Documentation means I can look in the manual and the info is right
    Paul> there, properly referenced in the table of contents and in the
    Paul> proper section for that type of language feature, unified with the
    Paul> rest of the docs.

I was suggesting that maybe you might like to take the pieces and make them
something coherent.  If it was trivial it would have probably been done by
now.

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

    Paul> I've personally been happy with Texinfo for other kinds of docs
    Paul> and would consider it easier to deal with than latex2html.  It
    Paul> might even be feasible to edit it in a wiki, so anyone could
    Paul> improve it easily.  Another idea is web-based doc comments like
    Paul> PHP and MySQL have, so the doc editors can incorporate the info
    Paul> from the comments in subsequent doc releases.

I rather like reST (much of www.python.org is being reimplemented in reST),
but that's just me.  The key point I was trying to make is that an
annotation capability would probably help.  With such a feature you could
add examples or links to the online Python Cookbook, whatever.  Need some
ideas?  Look here:

    http://www.amk.ca/diary/archives/003336.html

As Andrew indicated, it's a "half-hour hack", but it might give someone
something to think about.

Skip