[Python-ideas] A Wiki-style documentation with an approval process
tjreedy at udel.edu
Fri Nov 21 22:36:08 CET 2008
Ezio Melotti wrote:
I have thought of the same idea, as have others, but decided not to
> 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
> 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
> 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  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
> 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 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
Terry Jan Reedy
More information about the Python-ideas