Certainly interesting, but it is important to keep some quality to
control. I think a line can be found to tread in the middle. There has
been a lot of talk about the possibility of adopting distributed
version control, and we already have mirrors in place officially and
unofficially. I could imagine such a documentation editing being
committed to branches in such a system.
I'm not completely sure there are enough changes needed to the
documentation to warrant it, however.
On Fri, Nov 21, 2008 at 8:49 AM, 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 _______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
-- Read my blog! I depend on your acceptance of my opinion! I am interesting! http://techblog.ironfroggy.com/ Follow me if you're into that sort of thing: http://www.twitter.com/ironfroggy