Doc suggestions (was: Why "class exceptions" are not deprecated?)

[Ed Singleton]

On 29/03/06, Fredrik Lundh <fredrik at pythonware.com> wrote:
> rurpy at yahoo.com wrote
> > write a tutorial as good as what is already there.  But what I can
> > do is report problems I find when using it, and make suggestions
> > about how to avoid those problems.
>
> There's no shortage of ideas -- nor people who can write a tutorial
> that's better than the current one (which is far from optimal, mostly
> thanks to a zillion peephole edits over the years).  There's a shortage
> of volunteer time, though.  That's why the "I'm just the idea guy,
> someone else will have to provide the hundreds of hours required
> to implement my idea" arguments are so offensively meaningless.

I'm not entirely sure there is a shortage of people who want to
volunteer, just that a lot don't know that they can volunteer, and
those that do can't make a huge time commitment or don't have the
confidence.

I think there's quite a lot of people who would be happy to help out
as and when they could (particularly with small edits like the one
mentioned), if they were sure someone else was going to double check
that they hadn't accidentally written garbage.

This would be a perfect situation for a wiki.  I think it would be a
good experiment to have a wiki containing the documentation (separate
from the main documentation and clearly marked experimental for the
moment), and to see if it did self-organise as wikis often do. 
Beginners like rurpy could add comments when they don't understand a
paragraph, more confident people could attempt to correct the
paragraph, and every now and then an advanced person could scan
through it and make sure it was truly accurate.

It would greatly reduce the work need by the people currently
responsible for documentation (they just have to read through and make
sure things are correct) and if a page has been significantly improved
by the community and double checked by an expert, it could be promoted
to the official version of the documentation.

If the whole thing descends into chaos, the wiki (pages) could just be
deleted and we continue with the current system.

As Python has such an excellent community, it would be a shame not to
give them more responsibility in this area, and this system seems to
be working quite well for many python projects (many just use the wiki
in Trac).

Ed

(I'm actually tempted to just copy and paste each page from the
tutorial into the current wiki but I'd hate for it all to be deleted
after doing that).