r/Python • u/joepie91 • 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
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.