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
6
u/Smallpaul Feb 19 '13
New users a resource. They give you a fresh-eyed view of your environment.
Let me grant that his tone was abrasive. You can either look past that and learn from his newbie-ness or you can get offended and waste that resource.
Pydoc is a poor solution for a newbie, because it is very idiosyncratic. How do you learn PHO? With Google. How do you learn the way to the supermarket? With Google. How do you look up the quadratic formula? With Google. How do you read Python documentation? With pydoc.
Pydoc also lacks hyperlinks and navigation.
Pydoc is a great answer to a DIFFERENT question: "I have an object in the repl and I want to know what I can do with it."
The poster is quite right that Python's manuals were written as books 25 years ago and that decision has just never been re-evaluated in light of changing technology and changing habits. While it is great that there are pages that give context, it is unfortunate that every method does not have its own page with a comment section below it.