Re: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation
On Wed, Nov 24, 2010 at 1:24 PM, Georg Brandl <g.brandl@gmx.net> wrote:
at <http://dpo.gbrandl.de/contents>, you can look at a version of the 3.2 docs that has the upcoming commenting feature. JavaScript is mandatory. I've switched on anonymous comments for testing, but usually at least comments from anonymous users can be moderated. Be sure to test the "propose a change" feature too. Login currently allows OpenID exclusively. Credits go to Jacob Mason, whose GSOC project is responsible for almost all of what you see there. [1]
Nice job.
Other things I have to do before this can go live:
* reuse existing logins from either wiki or tracker?
+1, Anonymous comments good too... mark
On Fri, Nov 26, 2010 at 3:52 PM, average <dreamingforward@gmail.com> wrote:
Anonymous comments good too...
I suspect anonymous comments fall into the same category as anonymous issue tracker submissions. We've disallowed those for good reasons, and those make sense in this case as well. For the moderator side of things, I wonder if it makes sense to actually create a tracker issue behind the scenes for each comment; that would take care of the discovery issue for maintainers. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> "A storm broke loose in my mind." --Albert Einstein
On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake <fdrake@acm.org> wrote:
On Fri, Nov 26, 2010 at 3:52 PM, average <dreamingforward@gmail.com> wrote:
Anonymous comments good too...
I suspect anonymous comments fall into the same category as anonymous issue tracker submissions. We've disallowed those for good reasons, and those make sense in this case as well.
Are you sure about that? The problem with general tracker submissions is that we almost always need additional information from the original submitter (what version, what platform, does it work if you try version X+1, etc). Opening up anonymous submissions would just mean more work for tracker folks in trying to reproduce the problems, failing and then closing them as "works for me" or "not enough information". None of those reasons apply to doc comments - "this is wrong", "this is unclear and would be better worded as 'make sure to do X before doing Y'" are potentially useful even if the docs editors never hear from the submitter ever again. The key difference is that the doc maintainers don't need to try to reproduce anything - they just read the comment, decide whether or not they agree with it and then either apply it, modify and then apply it, or else deep-six it, never to be seen again. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Am 27.11.2010 12:24, schrieb Nick Coghlan:
On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake <fdrake@acm.org> wrote:
On Fri, Nov 26, 2010 at 3:52 PM, average <dreamingforward@gmail.com> wrote:
Anonymous comments good too...
I suspect anonymous comments fall into the same category as anonymous issue tracker submissions. We've disallowed those for good reasons, and those make sense in this case as well.
Are you sure about that?
The problem with general tracker submissions is that we almost always need additional information from the original submitter (what version, what platform, does it work if you try version X+1, etc). Opening up anonymous submissions would just mean more work for tracker folks in trying to reproduce the problems, failing and then closing them as "works for me" or "not enough information". None of those reasons apply to doc comments - "this is wrong", "this is unclear and would be better worded as 'make sure to do X before doing Y'" are potentially useful even if the docs editors never hear from the submitter ever again. The key difference is that the doc maintainers don't need to try to reproduce anything - they just read the comment, decide whether or not they agree with it and then either apply it, modify and then apply it, or else deep-six it, never to be seen again.
I agree. I'd rather put in aggressive spam-filtering than block anonymous comments; this commenting really is about easy and quick feedback rather than an involved process. That said, it really depends on how people are using the comment feature once it's in place. If we see too many unqualified or nonsense comments from anonymous users, we can still decide to block them. Georg
On Sat, Nov 27, 2010 at 6:24 AM, Nick Coghlan <ncoghlan@gmail.com> wrote in response to my comment about anonymous comments:
Are you sure about that?
I'm quite certain. Experience will tell whether I'm right, of course.
The problem with general tracker submissions is that we almost always need additional information from the original submitter (what version, what platform, does it work if you try version X+1, etc). Opening up anonymous submissions would just mean more work for tracker folks in trying to reproduce the problems, failing and then closing them as "works for me" or "not enough information".
Right.
None of those reasons apply to doc comments - "this is wrong", "this is unclear and would be better worded as 'make sure to do X before doing Y'" are potentially useful even if the docs editors never hear from the submitter ever again.
Bug reports are also *potentially* useful even without further information from the OP. It may well contain enough information. Doc comments saying "this is unclear" or "this is wrong" can easily trigger a request for clarification: "What more did you want to know?" "Why do you think this is incorrect?"
The key difference is that the doc maintainers don't need to try to reproduce anything - they just read the comment, decide whether or not they agree with it and then either apply it, modify and then apply it, or else deep-six it, never to be seen again.
A comment that says the doc is wrong may well trigger an attempt to use the API in question, and confusion because the comment didn't include enough information to identify the specific can the OP is really talking about. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> "A storm broke loose in my mind." --Albert Einstein
participants (4)
-
average -
Fred Drake -
Georg Brandl -
Nick Coghlan