Social problems of Python doc [was Re: Python docs disappointing]

[Antoine Pitrou]

r <rt8396 <at> gmail.com> writes:
> 
> On Aug 9, 11:02 pm, David Lyon <david.l... at preisshare.net> wrote:
> > Since you're talking about documentation, which is a part of python,
> > don't you think you should be discussing it on python-dev ?
> 
> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
> idea, lets go to the IRS and see if we can persuade them to stop
> taxing us...

You know, the most interesting thing in this thread is certainly its title :
« Social problems of Python doc »

Yes, the little social problem here should be clear: if you have complaints to
voice or improvements to suggest to the Python docs, you should do so on the
issue tracker (*). For most topics, this is the only reasonable way to signal
problems to the Python developers community, and so it is in most free software
/ open source projects.

Just because you are able to write tongue-in-cheek (**) comments on python-list
or, even worse, on a third party website, and generate a long thread about how
Python doc (supposedly) s*cks
1) doesn't mean there is a legitimate issue (we all know how people can quickly
inflame about empty subjects)
2) even though there can be a legitimate issue, doesn't mean Python developers
will go out of their way and parse the entirety of the messages to find
potentially useful data in them. The bug tracker is the place for this, and it's
your task, if you want to help, to submit suggestions in it.

FYI, the Python doc is very actively maintained nowadays, and bug reports /are/
taken into account. If you think you've got a lot of time for ranting about how
the doc sucks, but don't want to spend the couple of minutes needed to post
issues on the bug tracker, it speaks a lot about your motivation. Admittedly, in
every successful community, there are attention seekers who are not interested
in actual participation.

(*) http://bugs.python.org

(**) yes, humour is fine, but it doesn't replace actual, informational content


Antoine.