[Doc-SIG] regarding the current state of Python docs

[John M. Gabriele]

Hi,

I've just joined this list, and judging from some of the
posts I've seen in the archives, there seems to be some
concern about a problem with the current way Python is
documented.

My guess is that the current system looks something like
this:

1. checkout the doc source
2. make changes
3. commit changes


Personally, I think the best way document Python (outside
of the built-in docstrings) is a wiki but with only a select
group of folks with edit privileges. That is, only after
you've been around for a little while (or otherwise shown
that you can write good docs and want to help) are you given
edit access. Nothing too strict. Just limited to folks who
actually want to help, and who can show they're fairly
good at it. The same way you grant committer access on any
free software project.

It seems like it wouldn't *too* be much trouble to simply
take all the docs as they currently are and export them to
a new wiki, wholesale. That is, create a "sister" wiki to
the one we already have. Put the whole enchilada on there.
The library reference, the language reference. Everything.

Editing a wiki page is *way* easier than doing the checkout-
edit-commit procedure as outlined above. Sometimes I've only
got 5 or 10 minutes, and really would like to see a small
clarification in the docs. If it were wikified, I could
make that change (say, on my slashdo^H^H^H lunch break).
If I'm at work, and had to do a checkout, etc, ... no way
would I bother. It would have to wait 'til I get home -- then
with the wife and kids wanting some family time, the edits
might not even happen.

How hard is it to convert html to suitable moinmoin wiki
text input? Is there already a tool for this? Maybe someone
needs to just jump on it, pull the starter on the chainsaw,
just go for it, and let the chips fall where they may. :)

---J


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com