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

[Calvin Spealman]

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