improving the Python docs -- a wiki? copy PHP's model?

Skip Montanaro skip at pobox.com
Wed May 5 14:31:08 EDT 2004


    Mike> A good example of this just came up in this group a few days
    Mike> ago. A new Python programmer was puzzled over this result:

    >>>> text = 'zone "newsouthpine.com" {'
    >>>> text.lstrip("zone \"")
    Mike> 'wsouthpine.com" {'

    Mike> He did read the documentation for lstrip, but the doc doesn't make
    Mike> it at all clear that the argument to lstrip is treated as a set of
    Mike> characters.

    Mike> With the PHP documentation model, there would have been a user
    Mike> comment and example attached to the lstrip doc explaining this.

As a first step perhaps someone can it upon themselves to mirror the library
reference manual's structure in the wiki and start adding missing examples,
comments, etc.  If what's there becomes significant enough, medium term I
think one or both of these will happen:

    1.  Content will migrate from the wiki to the libref manual.

    2.  Links from the online libref manual will be added that refer to the
        comment/example pages in the wiki.

Longer term, perhaps a more tightly integrated system can be developed.
Note however that the current system uses latex2html to generate the online
documentation and that there is very limited extra time with the current
people actively doing Python documentation.

I created a Python Glossary wiki awhile back:

    http://manatee.mojam.com/python-glossary

with the intention that it would serve as raw material for the glossary in
the Python tutorial.  I return to it ever-so-rarely to migrate content from
it into the glossary in the tutorial.  It would be great if someone could at
least take over the review process.

Skip




More information about the Python-list mailing list