[Python-ideas] A Wiki-style documentation with an approval process

[Ezio Melotti]

As far as I know, the only way to report a typo or change something in 
the documentation is actually open an issue in the bug tracker.
This implies that:
1. If the user is not registered to the bug tracker he can't open the 
issue, and he won't probably register for a small mistake;
2. The user has to spend some time to reach the bug tracker page, open a 
new issue, write a brief description of the problem and possibly create 
and attach a patch;
3. A developer (of Python) has to read the issue, write a patch or check 
if the attached patch is ok and then apply it (even if I think that some 
developers can edit the doc directly).
In my opinion this is rather clumsy and certainly not user-friendly. 
Even if the user is registered to the bug tracker and knows how to 
report an issue (and this is already a small subset of the doc readers) 
he may not want to go through all these step just to fix a typo.

The idea is to allow all the users to edit the documentation pages 
directly (like a wiki), but wait the approval of a developer before 
apply the changes.
The steps will then be:
1. The user finds a mistake, clicks on an [edit] link and fixes it;
2. A developer check if the correction is ok and approves of refuses it.

This will also lead to the following benefits:
1. All the users can contribute even if they are not registered and/or 
they don't know how/where to report the problem;
2. The process is simpler so the users are more likely to report 
mistakes, spending less time;
3. If the process is easy enough, users may want to submit some example 
or tip that could be useful to others;
4. The developers just have to check and approve/refuse the changes. 
Again, this will require less time and they will be able to fix several 
mistakes in few minutes (if not seconds);
5. The bug tracker won't be "polluted" by issues regarding typos and 
other small mistakes in the doc.

Problems and limitations:
Even if probably there's already something like this out there, I don't 
know how easy it is to find/implement it. It shouldn't be too hard to 
write something ex-novo, but then again, someone will have to do it. 
Something like this works well for self-explanatory corrections (like 
typos), but it could not be the best when you have to explain the 
reasons of the change. Possible solutions are:
1. Allow the user to write an (optional) comment to the correction (e.g. 
"Changed xyz to match the new docstring.");
2. Open an issue where to discuss about the correction and then edit the 
page (some developers could have direct access to the page so they can 
edit them immediately -- I don't know if there's already something like 
that now or if they have to apply patches);
3. Have a "discussion page" like the the ones that are commonly used in 
wikis.

I don't know how feasible this idea is, but I'd really like to have a 
simpler way of editing the doc. It would also be nice, if the users 
could contribute actively to improve the doc, adding more exampes and 
pointing out possible pitfalls (and the developers' approval will still 
assure correctness).

--
Ezio Melotti