[Python-ideas] A Wiki-style documentation with an approval process

[Stephen J. Turnbull]

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?