[Python-ideas] A Wiki-style documentation with an approval process
ezio.melotti at gmail.com
Fri Nov 21 14:49:11 CET 2008
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  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
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
More information about the Python-ideas