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 <brett@python.org> wrote:
> On Fri, Nov 21, 2008 at 05:49, Ezio Melotti <ezio.melotti@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.
> >
>
>
> 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
>