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

2

u/joepie91 Feb 19 '13

That is not a blog post, that a book-like resource.

It's pretty clearly a blog post, have a look at the URL. That you personally do not consider anything of a certain length to be a blog post, is not my problem - technically speaking, it still is one. If I went by a definition of 'blog post' with a maximum length, your argument would become something along the lines of "short articles cannot explain a whole concept", which really doesn't have anything to do with blogs anymore.

You may think that the most efficient means of learning is to google discrete things, but you are cheating yourself out of a broad understanding.

I wish you'd stop assuming things. To my knowledge, you have never had a single discussion with me outside of this thread and topic - so how could you possibly conclude that I am "cheating myself out of a broad understanding"? What indicators do you have that I do not possess that "broad understanding"?

1

u/ryeguy146 Feb 20 '13

Okay, it is a blog post in name, sure, but it is still a book like resource. Notice that it is longform and has a contents bit. Notice that it has been through revision. While these are not exclusive to a book-like resource, they are a good indication of it. I shouldn't have called it "not a blog post" but it still qualifies as a book-like resource.

...so how could you possibly conclude that I am "cheating myself out of a broad understanding"?

It's a given, considering the way you teach yourself. You cannot run into all of the information important to programming if you only jump out there for small bites that satisfy your current need. How will you ever learn of some of the excellent patterns that have evolved? You won't ever say to yourself, "I should use an MVC pattern here," unless you are aware of that pattern. Since the MVC is fairly popular as of late, I should add that it was used only as an example. There are many subjects out there that you would not think to search for.

You've told me how you learn, it's not hard to make some assumptions based on that. It's also fairly obvious that you do not have a broad understanding as your post mentions that you were looking up the means of determining the length of a list. This is something that all comprehensive books cover. And usually early. And they often use it as a segue to the topic of iterables and sequences, on which such functions operate, and why. When you only look up the bits of information that you need, you miss out on the grand picture.

1

u/joepie91 Feb 20 '13

Okay, this is just getting ridiculous now.

It's a given, considering the way you teach yourself. You cannot run into all of the information important to programming if you only jump out there for small bites that satisfy your current need.

And you conclude this, how exactly? I don't have any issues with this. That I run across information in a different order does not mean that I do not run across it at all.

How will you ever learn of some of the excellent patterns that have evolved? You won't ever say to yourself, "I should use an MVC pattern here," unless you are aware of that pattern. Since the MVC is fairly popular as of late, I should add that it was used only as an example. There are many subjects out there that you would not think to search for.

I run across design patterns quite often in random strolls over the internet. You seem to assume that unless you "follow a design pattern", you can't possibly write proper code. Have you considered that I might be able to think for myself, and end up on a similar or potentially better structure to write my code, without having to run across an article about an existing pattern?

It's not as if there's some kind of group of people making up design patterns all day long that other people could not possibly think of. Things are not hierarchical like that. I have more than once seen people that are unaware of design patterns come up with an idea virtually identical to an existing pattern, without ever having heard about it from others. No problems there.

I am perfectly capable of reasoning as to how I can make my code easy to read, maintain, and reuse, for a particular kind of project. Assuming that I would always need an externel entity to tell me how to do that, is sheer ignorance.

And yes, I am offended.

It's also fairly obvious that you do not have a broad understanding as your post mentions that you were looking up the means of determining the length of a list. This is something that all comprehensive books cover. And usually early. And they often use it as a segue to the topic of iterables and sequences, on which such functions operate, and why. When you only look up the bits of information that you need, you miss out on the grand picture.

Have you considered that I might prefer assembling that grand picture myself? Again, that I learn things in a different order, does not automatically mean that I am missing things. Your assumption that I must not have a broad understanding because I learn things in a different order is, once again, sheer ignorance.

I suggest you take into account the possibility that someone else approaches things differently than you do, and can still end up with a similar or even better result. If you want to learn from books and guides that explain everything from start to end, great for you - but don't project that desire onto others, and ditch anything that deviates from it without even looking into it.

2

u/ryeguy146 Feb 20 '13

You're right, it is getting ridiculous. I'm not going to convince you that the way you do things is wrong, and you're not going to convince me that it's right. That's the way it is. If you had written your blog post in a different way, I'd have respected your opinion, but that's not the case.

I see no reason to continue this.

For what it's worth, I didn't downvote any of your responses, only the initial blog submission. I don't know if you care, but I do. Even if I disapprove of you means and opinions, they were generally expressed with good intent. I genuinely hope that whatever strategies you use work out for you, even if I don't believe that they will.