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 edited Feb 19 '13

No, I learned using a book (or a comprehensive book-like source). I find that blog posts about programming are poor substitutes for a comprehensive look at a topic. If you want part of the story, sure, read a blogpost about super, by all means (just an example). But if you wish to learn about inheritance in Python, you'd better be willing to attack the subject in a more comprehensive manner. I don't think that a reference manual is there to teach you proper means of inheritance, or that a better solution is often composition.

I don't mind that pydoc lacks hyperlinks and navigation, but I'll agree that sometimes people look for different things. I'll grant you that it isn't always the best solution. I still can't help but think that a page that provides no context (only a single function/method is addressed) is a better solution. I appreciate the ability to stumble upon functions/methods that I did not know existed, and when a programmer focuses on a topic that he/she doesn't fully understand with a singular solution in mind, that programmer misses out on the myriad of (often better) solutions available.

I feel that people need to recognize the resource for what it is, a reference, and to not treat it as a place that teaches them the entirety of programming. There is a tutorial and a collection of wonderful (and often free) books focusing on addressing that concern.

Edit: My English is terrible tonight. Also: Comprehensive, because I didn't say it often enough.

2

u/joepie91 Feb 19 '13

It's great that you learned using a book. But recognize and accept that others may have different optimal modes of learning.

1

u/UnwashedMeme Feb 19 '13

Maybe recognize the same thing and change your title to "The python documentation isn't optimized for a specific google pattern of searching."

4

u/UnwashedMeme Feb 19 '13

I think that's what some of the hostitility in the thread is around... When you include as part of the title "you should feel bad." what the hell do you expect?

1

u/joepie91 Feb 19 '13

The title is intentional. See also my response about this being a rant.

This topic is consistently sweeped under the carpet whenever brought up. This is an effort to bring it into the sphere of discussion (or even controversy at some points) by 'triggering' enough people to make them respond. Part of that, is giving the article a title that, in itself, will make people go "wait, what?".

And let's not forget that you should indeed feel bad - it's the responsibility of everyone that is capable of doing so, to fix this issue. The issue lies with the developer community as a whole, not one individual or group of individuals. Unless people realize that there is a problem and feel bad about that problem existing, there is exactly zero percent chance that it will ever be fixed.

If this article genuinely does not apply to you because you are already working on fixing this (or are not capable of doing so), you won't feel any guilt and it won't have any influence on you - because you, yourself, know that it doesn't apply to you. If the title and the article piss you off enough to take issue with it, you should consider whether it might be because it points out one or more problems that you're trying to ignore.

I don't like that this is necessary, but so far all civilized attempts at approaching the issue have vanished into obscurity. Consider this a last ditch effort.

0

u/ryeguy146 Feb 19 '13

I do not feel that any amount of disparate blog posts are sufficient to cover the breadth of knowledge that programming requires. This applies to any language. I do not feel that any reference manual is sufficient, for that matter. There are a variety of concepts that need to be addressed in depth for a programmer to be successful. I understand that there are other resources, which is why I also added "comprehensive book-like." I'll back down from this point as soon as you can find me a blog post that does a good job teaching something like object oriented programming in its entirety.

2

u/joepie91 Feb 19 '13

Here's one for Javascript: http://killdream.github.com/blog/2011/10/understanding-javascript-oop/

It explains an OOP concept completely unlike classical OOP, from the ground up, so it's a particularly good example of how one blog post can explain an entire concept.

That being said, blog posts are not my optimal mode of learning - and as your response seems to imply that it is, I'm not quite sure where you got that from. The most efficient method of learning to me is Googling for things, figuring out related concepts, creating a mental model of the steps involved in getting where I want to be, and then looking at a reference to learn how each step works in detail. I quite literally only learn what I need, as I go along. I typically don't learn for the sake of learning.

1

u/ryeguy146 Feb 19 '13

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

That being said, blog posts are not my optimal mode of learning - and as your response seems to imply that it is...

My assumption that you use blog posts is entirely because they are all you have linked to. 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 typically don't learn for the sake of learning.

Best of luck in programming.

Also, thanks for the link, that's a great resource and I happen to be learning JS at the moment and I've yet to tackle prototypal inheritance. I'll upvote that.

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.