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