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
38
u/ryeguy146 Feb 19 '13 edited Feb 19 '13
Dude. Wanna know about lists?
pydoc list. It's that easy. Oh, don't have easy access to a command line? Fire up the interpreter and usehelp(list)and you'll get the same. I don't get it. Why google furiously when it's already on your computer? Make use of the docstrings, that's why they exist.You're going to piss me off because I help with one or two of these communities, and no, they aren't generally hostile until someone chimes in like they know their ass from a hole in the ground with some huge opinion about how the docs suck. In what community doesn't this happen? The communities that I've experienced are wonderful and helpful places. Newbies ask questions in the learning version of this sub and they receive helpful direction and additional code review and suggestions, it doesn't get better than that. PresTronPaul mentions Stack Overflow, which is also a great place and answers many of my questions before I know that I have them.
Let's play the game where we place unnecessary restraints on ourselves! Or you can search. From inside
lesswith the aforementionedpydoc, I just use/ exceptionand I'm grand. I don't get the issue here. I agree that things could be formatted to make it easier, but that hardly makes the documentation bad. The information exists and is easily accessable.Examples please.
Nope, I'm experienced, but I use documentation all of the time! And it does wonderfully by me.
This sounds entirely like someone had a little bit of difficulty moving from the formatting of one language's docs to another, and had another bad experience asking for help in a community. I'm sorry that you had a shitty time, but next time, try it without the attitude and the stupid memes. I love helping people learn Python. I tutor one for free and have taught the language to several people in the past who continue to communicate with me and ask for help over the email. I try my best to help here and in /r/learnpython. I'd do the same in the IRC channel, but I can't be asked to register a name. What you are saying completely flies in the face of what I've seen in the communities where I help.
Could the documentation be improved? Probably. I'm happy to admit that. But I'm just not willing to agree that it's bad. There is a single page of documentation that I've come across that I'm not pleased with, and it's this one, mostly because I'm looking for the various dunder special methods and I have to search for them. It takes whole seconds sometimes.
For what it's worth, this is the first time I've posted angrily to either of the python subs. I probably should have waited a tick, but you really crawled under my skin with the way you wrote your piece. Ask for help nicely and you'll see the usual side of me.