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

[Terry Reedy]

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