Ezio Melotti wrote: I have thought of the same idea, as have others, but decided not to propose it.
As far as I know, the only way to report a typo
There are rather few left I think. I and others report all we notice.
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;
If the user is not registered to the wiki.... ditto. Actually, the wiki has some problems. When I forgot my password and clicked 'Email me ...', it sent me a link to the wrong page with a password that did not work. I reported it but it apparently will not be fixed.
2. The user has to spend some time to reach the bug tracker page,
or the wiki page. Actually trivial in either case.
open a new issue, write a brief description of the problem
This does take longer, but not near as long as thinking about what words to write.
and possibly create and attach a patch;
The doc maintainers seem to be happy to either copy,paste,format from ascii text submissions or rewrite in a style they think better fits their idea of the Python doc style. They probably do this faster than I can write the text to copy and paste.
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.
Do you know any such 'he's?
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.
I suspect that the doc maintainers would spend as much time rewriting submissions as they do now and more time rejecting suggestions. Since suggestions would be hidden until approved, they could also get conflicting suggestions, or repetitions of rejected suggestions. Non-maintainers would not be able to improve suggestions. With the tracker, everything is visible and searchable (which is not to say that it could be be made even better).
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;
If you are right, they are also more likely to make suggestions ranging from the inane to high quality but stylistically not fitting.
3. If the process is easy enough, users may want to submit some example or tip that could be useful to others;
I strongly feel examples and tips should be separate docs. People could do that with the wiki now. But, of course, that would require learning the wiki formatting language.
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);
They would still have to copy changes back to the master .rst copy in the repository, so I see little time saving if any. But they can decide that.
5. The bug tracker won't be "polluted" by issues regarding typos and other small mistakes in the doc.
Tracker pollution is issues like 'why does 1.1 print as 1.1000000001'. Many doc issues *need* discussion before a new text is decided on.
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.");
That is what one can do with the tracker.
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.
Wikis have one discussion page for each wiki page, with all discussions that one page jumbled together and never really closed. After a few years, it can become a mess. Tracker discussions are separate for each issue. Once closed, new issues start fresh. Participants in a particular issues are automatically notified of new posts to that issue, but only to that issue. Tracker issues and discussions are not limited to one section of one document. I have submitted issues that involved both the language and library manuals. Terry Jan Reedy