Do you feel bad because of the Python docs?

[Rick Johnson]

On Tuesday, February 26, 2013 7:48:51 PM UTC-6, Terry Reedy wrote:
> On 2/26/2013 1:52 PM, Devin Jeanpierre wrote:
> > 
> > [...snip legit complaint...]
> > 
> Have you opened an issue, or checked for existing issue? I would be open 
> to the idea that entries like that for int should not be overly type 
> specific and imply that the defaults are the only possibilities.

Terry (with all due respect), do you /really/ expect that people have the time to open an issue on the bug tracker? Do you really think that everyone who uses python even knows about the bug tracker? Do you really think that people will believe that their opinion is worthy of placing on the bug tracker? Do you really?

I think most will just end up ignoring the docs and either be forced to give up on Python or look for documentation elsewhere. Now, you could react to that truth by saying:

 "Well, who cares! The docs are the docs and if people can't grok them then too bad for them because i think they are awesome."

Sadly (in actuality) it's too bad for *you* Terry (along with the many other people who maintain docs) when you ignore the many request for changes. Remember, if people just ignore the docs because of these abominations you and everyone else are basically wasting your time maintaining the docs! Do you understand this fact?

Terry Implies: "We will write the docs how *we* see fit, and to hell with your feeble misunderstandings. You are beneath us! *We* are the anointed ones. *We* know everything!"
 
Look i know your intentions are noble, and yes my wording was a bit theatrically unfair, but this is /exactly/ how people are interpreting your intentions Terry. Please don't become a zealot. Python will never be perfect! I can assure you.

And besides, is a bug tracker /really/ the place to voice the many legitimate problems concerning python's documentation or stdlib? Forgive me, but I thought bug trackers where for tracking ,umm... well, BUGS! 

This is why i mentioned the need for an official "PyWarts" (group or list) so these folks will have a platform to voice their frustrations. A very PUBLIC and very ACCESSIBLE and very WELL KNOWN platform. Because if IS NOT all three of these things, then it IS nothing.

But you cannot just hand them a microphone and then stick your fingers in your ears. You need to /listen/ carefully and try to place yourself into their shoes. I can assure you that the Python docs, and the language itself, could use some polishing. Stop taking these complaints personally and start listening with an objective ear; please?