Re: [Python-Dev] documentation comments

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] documentation comments

A.M. Kuchling
On Thu, Dec 22, 2005 at 09:27:06AM +0000, Steve Holden wrote:
> Could the PSF help here by offering annual prizes for the best
> contributions to the documentation, or wouldn't that be an adequate
> motivator?

I think the most effective thing would be to award a grant to someone
to build a real comment-on-the-docs system.  There were a few Summer
of Code proposals for this sort of thing; one was funded but the
developer decided to do a KDE project instead.  

I had lunch with Fred the other day, and he was worried about whether
anyone would garden the comments to remove spam.  That is indeed an
issue, but I think we can cope with that problem once a system is
built.

Another worry is versioning.  Once lots of people have made comments
on Python 2.4.0's documentation, what do you do when 2.4.1 is
released?  Do you move the comments to the new docs, or leave them
attached to 2.4.0 and start 2.4.1 with a clean slate?  (Perhaps the
system could work a little like a bug tracking system; comments could
be marked as 'applied', and applied comments don't get moved from
2.4.0 to 2.4.1 because their content is now in the docs.)

--amk
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] documentation comments

Fred Drake-3
On Thursday 22 December 2005 09:22, A.M. Kuchling wrote:
 > I had lunch with Fred the other day, and he was worried about whether
 > anyone would garden the comments to remove spam.  That is indeed an
 > issue, but I think we can cope with that problem once a system is
 > built.
 >
 > Another worry is versioning.  Once lots of people have made comments
 > on Python 2.4.0's documentation, what do you do when 2.4.1 is
 > released?  Do you move the comments to the new docs, or leave them
 > attached to 2.4.0 and start 2.4.1 with a clean slate?  

This was actually a big part of my gardening concern: comments from the
release X.Y.Z docs need to be handled before releasing X.Y.Z+1 or X.Y+1.*, or
they aren't being used to improve the documentation at all.

 > (Perhaps the
 > system could work a little like a bug tracking system; comments could
 > be marked as 'applied', and applied comments don't get moved from
 > 2.4.0 to 2.4.1 because their content is now in the docs.)

I'd be more inclined to see that comments are handled (even if handling them
is a matter of determining that they aren't actually interesting), and just
toss comments for a new release.  A patch release would be an occaission to
turn off commenting on the previous releases for the same X.Y version (though
comments would still exist in the older version).


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] documentation comments

Bugzilla from nnorwitz@gmail.com
In reply to this post by A.M. Kuchling
On 12/22/05, A.M. Kuchling <[hidden email]> wrote:
>
> I had lunch with Fred the other day, and he was worried about whether
> anyone would garden the comments to remove spam.

I would help assuming this is easy--meaning a single click to remove a comment.

n
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] documentation comments

Fred Drake-3
On Thursday 22 December 2005 13:44, Neal Norwitz wrote:
 > I would help assuming this is easy--meaning a single click to remove a
 > comment.

It looks like the system the MySQL folks are using makes it easy, but I've not
tried polluting their documentation with tests, just in case.  :-)

In general, my worry is less with dealing with spam than with ensuring
integration of content enhancements before release candidates go out.


  -Fred

--
Fred L. Drake, Jr.   <fdrake at acm.org>
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] documentation comments

Facundo Batista-2
2005/12/22, Fred L. Drake, Jr. <[hidden email]>:

> In general, my worry is less with dealing with spam than with ensuring
> integration of content enhancements before release candidates go out.

Well, I think that the most important part of annotable documentation
is just cuantitative feedback, not cualitative.

I mean, I don't care if a doc page has a comment and it doesn't get
included in the next release (if you want it included, submit it in a
more formal way).

But, if there's a page with 25 notes, that implies that there's a
problem with that doc page, and something (integrating some of the
notes or not) must be done with that text before the next release.

.    Facundo

Blog: http://www.taniquetil.com.ar/plog/
PyAr: http://www.python.org/ar/
_______________________________________________
Python-Dev mailing list
[hidden email]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/lists%40nabble.com