On Fri, Nov 21, 2008 at 05:49, Ezio Melotti 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 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

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?

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 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.