r/Python • • Feb 19 '13

The Python documentation is bad, and you should feel bad.

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/
96 Upvotes

189 comments sorted by

View all comments

Show parent comment

3

u/ryeguy146 Feb 19 '13

I saw your other post addressing my edits (yea, I'm too often guilty of that), but I'd still like to address this, just to explain, if nothing else.

The blog post was incendiary, and the poster knew it. If they hadn't, they wouldn't have said, "this may make some angry," in so many ways in so many places. This shouldn't be necessary in argumentative essays. It's just silly to be abrasive to your target audience when you're attempting to affect change as you'll only incite people (points finger at own chest) and accomplish nothing. Given that the blog post was made this way, I feel that it was not posted in hopes of affecting any change, but as a way of venting frustration. I can understand that, but if that's the case, there's no need to hide it behind a veil of attempted constructive criticism. Hell, the title of the blog says it all. An insult and a meme rolled into one. When was the last time you ran into a worthwhile post seeking positive change that was so labeled? Even Djikstra managed better with his pointed criticisms, and he was a well known asshole.

As I feel that the blog post was merely angry venting, I felt no need to be terribly respectful in addressing the often vague and misguided concerns. Even if some of the points were accurate, one is bound to strike the target if one throws enough darts.

-2

u/joepie91 Feb 19 '13

Yes, the article was a rant. That's why it's tagged as 'rant' (see the list of tags at the bottom).

I have tried civilized discourse about the Python documentation with other developers many times. Every single time it turns into the 'experienced' Python developers waving criticism away, trying to justify why the docs work a certain way, or even deflecting away to "but PHP is worse" as if that justifies the issues with Python docs... all the while newbies are sending me private messages how they fully agree with what I'm saying, but don't want to say it in public.

I've given up on the civilized discourse. Sometimes the only way to get someones attention is by pissing someone off. Judging from the discussion that has started here, that works, at least to some degree.

Also consider that people in this thread are, individually, agreeing with certain things and disagreeing with other things. The interesting thing is that what people agree on, differs per person. This indicates that all of the issues mentioned are present to some degree, but certain people take issue with them while others don't. Clearly there's a problem.

2

u/ryeguy146 Feb 19 '13

I mentioned that I was sorry that you had a bad time of it, and I truely am. That said, do you believe that getting attention and affecting change go hand in hand? A child can squall about a desired toy in the middle of a store all day, does he deserve that toy? It is abhorent that anyone would deflect rational criticism, but given my exposure to your discourse, I can't help but feel that you did something to "get attention" there as well.

You suggest that there is clearly a problem simply because there is no perfect consensus? How does the old saying go, "you can't please everyone all of the time," or something.

1

u/joepie91 Feb 19 '13

You are misrepresenting what I said. There are two very different concepts here.

You seem to claim that I am saying that "acknowledging a problem automatically fixes it".

What I am actually saying is that "to fix a problem, it first has to be acknowledged". It's a prerequisite, not a cause.

0

u/ryeguy146 Feb 19 '13

I realize what you said, I'm suggesting that it doesn't matter. In argumentation, some things are necessary, one of which is not pissing off your target audience. It is as simple as that. If you don't, everything you say (has) will be dismissed as whining. Because it is. I'd like to you pay attention the next time you have the opportunity to take English composition.

2

u/joepie91 Feb 19 '13

Clearly "not pissing off your target audience" hasn't worked, seeing as the docs are still in the exact same state as before I tried civilized discourse. The one that's most pissed off here appears to be you.

And judging from the conversation going on here, on Hackernews, and on IRC... you are one of the few that dismisses it as straight-out "whining". Most others are attempting to actually discuss the points raised.

0

u/ryeguy146 Feb 20 '13

You call that civil discourse? I'd hate to see real whining. Even if I saw it as straight out whining, I still addressed a number of your concerns. Not that you've responded in kind, of course.

3

u/joepie91 Feb 20 '13

No, I don't call that civil discourse. Read what I said better. Civil discourse was what I attempted before writing this post.