[Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation

[Fred Drake]

On Sat, Nov 27, 2010 at 6:24 AM, Nick Coghlan <ncoghlan at 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