A Wiki-style documentation with an approval process
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
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 <ezio.melotti@gmail.com> wrote:
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
On Fri, Nov 21, 2008 at 05:49, Ezio Melotti <ezio.melotti@gmail.com> wrote:
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.
Georg can correct me if I am wrong, but I believe he has been working on a commenting system for the docs for this exact need. Don't know how far along it is, but I am sure any help you can provide to move it along would be appreciated. -Brett
On Fri, Nov 21, 2008 at 05:49, Ezio Melotti <ezio.melotti@gmail.com> wrote:
As far as I know, the only way to report a typo or change something in
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
I believe that a commenting system could be very helpful. I have done some PHP coding and in my early years the chm that includes the comments was of great value to me since I never had an Internet connection at home so I would just download the document from a cyber cafe and hack away. In the case of Python, where I still don't have a lot of experience, the fact that I must always be online to find possible solutions to a problem can be quite a drag, still, dir and docstrings help a lot though. At that if I could help out, Georg, let me know how, I'm relatively new to this stuff but I would love to give back to the community, Python has made me quite some money. Kind Regards, Patrick Atambo. On 11/21/08, Brett Cannon <brett@python.org> wrote: the 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.
Georg can correct me if I am wrong, but I believe he has been working on a commenting system for the docs for this exact need. Don't know how far along it is, but I am sure any help you can provide to move it along would be appreciated.
-Brett
_______________________________________________ Python-ideas mailing list Python-ideas@python.org http://mail.python.org/mailman/listinfo/python-ideas
On Sat, Nov 22, 2008, Patrick Atambo wrote:
In the case of Python, where I still don't have a lot of experience, the fact that I must always be online to find possible solutions to a problem can be quite a drag, still, dir and docstrings help a lot though.
Well, Python does make it easy to download the HTML docs; that's what I've done for years to have a local copy handy. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "It is easier to optimize correct code than to correct optimized code." --Bill Harlan
Patrick Atambo wrote:
I believe that a commenting system could be very helpful. I have done some PHP coding and in my early years the chm that includes the comments was of great value to me since I never had an Internet connection at home so I would just download the document from a cyber cafe and hack away. In the case of Python, where I still don't have a lot of experience, the fact that I must always be online to find possible solutions to a problem can be quite a drag,
The Windows installer installs a .chm version of the docs with a nice TOC and module index. It seems to have everything the .html version has except the general index. (I presume that because Help does not have within doc anchors). If you could use PHP .chm, cannot you use Python .chm also?
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
Terry Reedy writes:
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.
The really big differences between the bug tracker and a "wiki" seem to be (1) Anonymous "wiki" submission means no registration, which is a PITA for the bug tracker (I've a couple of users who religiously send PRs to the mailing list because they oppose using web interfaces that require registration on principle!) But these days even wikis are often requiring registration to slow down wiki spam. Specifically, Python's does. (2) Directly editing the document avoids the need to learn about the project workflow, figuring out appropriate people to assign to, the relevant module, applicable versions, etc. This is a quality vs. quantity tradeoff. IMO Python is among the best in terms of quality, and it's not hurting in terms of quantity. Don't fix what ain't broke. [WARNING: following taken out of context; used to be at end.]
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.
This is a crucial point. Wikis are good for free-form discussion, but Python's issues have a lot of extra structure that the tracker should take advantage of (even if it becomes more wiki-like in some ways). I think a better approach would be to find unnecessary impediments in the bug tracker, and eliminate them. I don't know of any in Python's (but I'm pretty familiar with it so I'm probably blind to its faults). One *possibly* unnecessary impediment is the roundtrip requirement of registering before being allowed to submit. In Roundup it would be straightforward to construct the new issue page to allow simultaneous registration. It would even be possible to "hold" the submission until the registration confirmation were received, I think, but that would be pretty hackish. [Back to original order.]
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?
C'mon, I bet you've let a typo or two slide because your brain was on fire to finish your latest hack. Haven't we all? If the doc you were reading was the wiki and a fix was a mouse click, two keystrokes, and another mouse click away, you might fix it in that situation. The thing is, fixing typos and style issues is important as a general indicator of quality (attention to detail), but going from 4 sigma to 6 sigma on typos just isn't that big a deal.
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.
Agree. Not a good thing.
Since suggestions would be hidden until approved, they could also get conflicting suggestions, or repetitions of rejected suggestions.
Fixable. Clicking on the edit link would bring up the pending changes to that page. Presenting these could be done as a series of diff -U1 hunks, for example. Conflicting changes would be marked in some special way. Each hunk gets a Defer/Approve/Reject radio button box if you have sufficient karma. Maybe there should be a Spam button too.
Non-maintainers would not be able to improve suggestions.
Not directly, but they could get access to previous suggestions as above and file a conflicting one.
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.
Agree. "Simple process good, simplistic process, not so good."
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,
This can be automated, but I can't say at what cost. You might have to rewrite the whole wiki software....
5. The bug tracker won't be "polluted" by issues regarding typos and other small mistakes in the doc.
Many doc issues *need* discussion before a new text is decided on.
Agree. Among other things, it can be useful to QA to know how many trivial issues are being fixed and by whom.
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.
Right, but one can't write a patch in the tracker the way you can in a wiki. Trac has its wiki/tracker "integration", but this kind of thing doesn't seem to be there. WIBNI you could pull up source (both code and doc) in the wiki and wiki-like edit it, which would then generate and optionally submit a diff against the official sources? (Not entirely serious, for the reasons you give about frivolous "contributions", but with appropriate controls, why not?
Stephen> But these days even wikis are often requiring registration Stephen> to slow down wiki spam. Specifically, Python's does. We've added ACLs to a number of frequently spammed pages, but in general we still allow anonymous contributions to the Python wiki. You can see that's the case if you visit the info link of most pages. For example I know the BayPiggiesGoogleMeetings page is frequently edited anonymously: http://wiki.python.org/moin/BayPiggiesGoogleMeetings?action=info Note that the editor column is frequently a hostname. OTOH, the FrontPage was frequently spammed as were a number of unusual pages. The form such spam takes is often about the same from one incident to another. My guess is there's a "root kit" for spamming wikis out there. It's probably a case of "even my grandmother could spam your wiki". Skip
Stephen J. Turnbull wrote:
C'mon, I bet you've let a typo or two slide because your brain was on fire to finish your latest hack. Haven't we all? If the doc you were reading was the wiki and a fix was a mouse click, two keystrokes, and another mouse click away, you might fix it in that situation.
1. There are very few overt typos left in the docs. 2. Why would I use such an inferior version as a wiki version would be? Now, if someone wrote a Microsoft Help workalike program that also included an 'email corrections' feature, that would be something else.
Terry Reedy wrote:
Stephen J. Turnbull wrote:
C'mon, I bet you've let a typo or two slide because your brain was on fire to finish your latest hack. Haven't we all? If the doc you were reading was the wiki and a fix was a mouse click, two keystrokes, and another mouse click away, you might fix it in that situation.
1. There are very few overt typos left in the docs. 2. Why would I use such an inferior version as a wiki version would be?
Now, if someone wrote a Microsoft Help workalike program that also included an 'email corrections' feature, that would be something else.
I agree with what Stephen J. Turnbull said. The main point here is "/making easy things easy/ and hard things possible". There are a several changes in the doc that don't require a related issue in the bug tracker and they would benefit from a wiki-like system (typos are just an example). If a change requires a discussion we can still use the bug tracker (and possibly edit the page directly at the end of the process, without using patches if they are not necessary.) This system is not intended as a replacement, but just an improvement of what we already have. Terry Reedy wrote:
I suspect that the doc maintainers would spend as much time rewriting submissions as they do now and more time rejecting suggestions. Among the Defer/Approve/Reject radio buttons that Stephen suggested we can also add an "Open as a new issue" button. This can be used to "redirect" on the bug tracker the suggestions that are valid but still need some change.
-- Ezio Melotti
participants (8)
-
Aahz -
Brett Cannon -
Calvin Spealman -
Ezio Melotti -
Patrick Atambo -
skip＠pobox.com -
Stephen J. Turnbull -
Terry Reedy