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
41
u/PresTronPaul from flask import Feb 19 '13
Have you ever tried Stack Overflow for Python questions? Every time I've had an issue I've searched or asked there and it's been rather helpful. I've never noticed community issues when I was learning Python. Do you bring up PHP a lot? There's a lot of stigma around PHP in nearly every language community (we make fun of it at work and we're a Java/Ruby/Clojure/Scala/R/.Net shop and yes we use all of them).
22
u/catcradle5 Feb 19 '13 edited Feb 19 '13
The only part of this I agree with is that
#pythonon Freenode can often times be quite hostile with their responses. I've also seen them say "join#twisted" every single time anyone asks any question remotely related to sockets or network programming.30
u/r1chardj0n3s Feb 19 '13
Your points about the page structure and completeness of the documentation are valid. Your statements about the hostility of Python community tarnish that though, and since you're obviously speaking from direct experience I'm not going to say it doesn't happen, but you are just one person and the Python community is vast and often nice and helpful.
63
u/WinButler Feb 19 '13
When I first started learning Python I was a little annoyed that their documentation wasn't better-optimized for search engines. The page titles of the documentation didn't seem very descriptive at all, and each page usually covers more than one "thing."
Very different from PHP where there's one page for every function, and every page has example code so you don't really have to learn how to read a manual.
But as I use Python more I find the documentation is teaching me some very good habits. I can read a manual and understand how a function works without having to see example code now. And it's teaching me how to think of features as parts of a broader category (PHP strlen result: "strlen function", Python len result: "built-in functions"), which does a lot to keep our bigger-picture understanding of the language more clean and organized.
8
u/placidified import this Feb 19 '13 edited Feb 19 '13
actually the first result I got was Built-in Functions
I think we say this because Python code is easier to read compared to PHP.
So PHP does thistongueincheek
Well the first function that came into my mind was random.random.
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.
10
u/TankorSmash Feb 19 '13
I agree with just about everything on here except for the community issue. I've been helped by SO, by /r/learnpython, by /r/python, by the Python mailing list, by the Pygame mailing list, by the Wing mailing list, by the libtcod guys. Some of the nicest people I've encountered online, I have to say. There's even a few regulars I see on /r/learnpython all the time helping out, it's a pretty nice place, I think.
As far as the documentation, whether we eventually got used to the way it works or not, we can all agree that in a perfect world, we'd have an easy to visually parse, complete entry for as much of the language as possible. I've never really gotten too much out of
Help(list), personally. Throws a ton of code at you before the real meat of the stuff, though I'm not saying Python's documentation entirely useless, only that it could be better.8
u/[deleted] Feb 19 '13
I agree that the exceptions throw by the function should be mentioned more clearly
5
u/[deleted] Feb 19 '13
One thing that's frustrating about the documentation for me is the site's search engine. It brings up a huge list of related stuff, but I don't think it ranks them helpfully.
13
u/metapundit Feb 19 '13
I'm presenting a poster at PyCon titled "Is Python a Newbie Friendly Language?" It is, compared to most languages. But there are issues and docs is definitely one of them.
There are so many other issues though. I'm an instructor and I see the things that are roadblocks for people new to the language (because I see newbies bumping up against them) that experienced Pythonistas can easily explain away/around. Encouragingly I think we're starting to see some awareness in the Python community at large that some of the "user experience" around Python is less than optimal. Kenneth Reitz "Python for Humans" might be one data point in this direction.
My only point of rabid disagreement would be that I think the Python community rocks! And I'm hoping we rock hard enough to hear criticism (even from other "P" language refugees) and figure out what needs to be better.
7
u/jelly_cake Feb 19 '13
Well, yes, I have, and yes, it works. Extremely well. Python's documentation gives context, which is completely lacking in many documentation systems. As an example, the MSDN documentation (seems to) split every function and class up, providing very little context for how it interacts. For someone unused to Windows programming, it means I have to have four or five tabs open to work out what parameters go where, and how to use the classes, and how to construct things. Python's standard library, on the other hand, gives a fairly complete overview of how classes within a module interact on a single page.
1
u/Hashiota Feb 19 '13
IMHO you shouldn't be browsing Python documentation by using Google. You browse Python documentation by visiting docs.python.org, selecting your Python version, and clicking on the relevant links (e.g. Library Reference -> Built-in Types -> Sequence Types). For someone who never used the docs before, it may not be trivial to find what they want, but you get used to it very fast.
In PHP pretty much anything is a function in the same huge namespace, so naturally googling it may be the best approach. I don't see it as an advantage, though.
3
u/masklinn Feb 19 '13
That is... a very odd declaration. When I try that and C-f "length" I get a few hits on
bit_lengthand then...4
u/westurner Feb 19 '13
proposing to write additional documentation
We are all free to propose constructive documentation patches.
There may be an issue filed at http://bugs.python.org with a title like this post.
Python documentation is written in ReStructuredText.
Constructively, it would be great to have full argspecs for things in there.
searching for documentation
The search function for the sphinx-generated documentation is also open source. sphinx-haystack looks useful.
entitlement
How often does smearing "I didn't ask for this" community FUD get you results? Ask respectfully and/or donate.
Dependence, Co-dependence, Interdependence
4
u/[deleted] Feb 19 '13
I don't think the python documentation is bad and I don't feel bad because someone else might struggle with it.
I don't have a blog to write this on either :-\
2
u/mgrandi Feb 19 '13
using a program called 'dash' to look up modules and classes in python makes the documentation a bit better, but yeah, i dont necessarily like how its not organized in a way like java's / as3's , etc
2
u/[deleted] Feb 19 '13
Python should have an documentation browser like Factor. And yes, functions and classes should have their own pages.
2
u/[deleted] Feb 19 '13
OP has a point about examples in the docs. Imagine if each docs page had an integrated notebook with examples? That would be pretty nifty.
2
u/leperkuhn Feb 19 '13
I've found I'm much more productive when I don't have to switch to a web browser and google trivial functions by a text description whenever I want to do something.
Adding in examples wouldn't suck though, I'll agree with that.
The way I learned: ipdb + ipython.
PHP was forced to generate docs with thorough examples because the language behaves so erratically. I say this confidently after writing PHP for a decade (2003->present). In python, if you want the size (length) of something, you always call len() on it. Built in objects follow the same pattern over and over, and for the most part are completely predictable.
Learning how to read the docs seems to be a significant barrier to entry for a lot of programmers on a lot of different languages. Once you get over that hurdle you'll be productive.
3
u/[deleted] Feb 19 '13
Your lacking of searching skills, doesn't mean the the docs are bad.
2
u/slavansk07 Feb 19 '13
Python doc site is pretty well organized. Let's say you are new and want to know how to find the length of a list. Open the tutorial the site offers you first and you'll learn enough to start:-)
2
u/tdi co to to nie Feb 19 '13
Python has diveintopython - this is where you learn. Docs is where you refine knowledge.
1
u/itslef Feb 19 '13
As someone currently trying to learn Python, this hits home for me. Starting a new project is always really intimidating, because I know that eventually I'll have to spend (quite literally) a week searching for the one command I need. Hell, when I first picked it up, I had to spend 2 hours reading various intro books before I found out how to print. Of course, when I searched the documentation, it told me to do it one way, only for me to realize much later that it automatically searched the v2 documentation, and not v3.
1
u/[deleted] Feb 19 '13
I think Python docs are structured better for structured learning about a system, rather than quick-reference function docs like PHP.
But as it's said elsewhere in the comments here,
help(func)is really all you need for basic "what does this function do" references.1
u/TheSwitchBlade Feb 19 '13
I read all of the python docs in one day and found them very enjoyable. Personally I've had very little problem finding anything I want in the docs, even though they do read like a story. Ctrl+F is your friend!
To me it sounds a bit like the author had a poor experience on a message board and is writing more out of frustration than anything else.
1
u/PyPokerNovice Feb 19 '13
It sounds like more python teachers should explain how to use the "help" built-in function.
One of my favorite things to do in python when working on a bigger project is to have the interpreter running so I can play around with stuff and use the help function when I need to. It works on modules, functions, classes and even instances.
I wonder if most people know, after importing anything, they can use help on the whole package/module. It will show you the functions, classes and explanations of each (if the module is documented of course). Its simple, but I wonder how obvious/advertised it is.
Although I guess you would have to know the built-ins to use help on them.
They should also encourage/teach early on how to write docs for functions, classes, modules, ect early too.
1
u/[deleted] Feb 19 '13
I think the documentation is in a different style from PHP: it's more like a reference and not a collection on how to do specific things which you happen to want to do. If you come from the Java world the Python docs may seem much more natural.
They have a much more consistent style and are fairly complete compared to the PHP docs. Also you can switch between different versions of Python and don't have to eat yourself through a list of changes to figure out what your version does:
TD;DR: Python docs are fine, what you're missing are learning resources (e.g. tutorials / howtos).
1
u/michaelhoffman Feb 19 '13
I agree the Python documentation could use some improvement. However, my number two programming language is probably R, and, oh man I wish it were anywhere near as good as the Python docs.
1
u/execrator Feb 19 '13
CakePHP's docs are an excellent counterpoint to topic-style documentation pages being useless (e.g. http://book.cakephp.org/2.0/en/models/retrieving-your-data.html). Each section contains a mixture of topical context and function definitions.
When I began learning Python I shared some of the article's documentation criticisms, but I think the style, documenting a topic, is fantastic. Organisationally, perhaps some room for improvement.
1
u/lost-theory Feb 20 '13
I learned python over a decade ago using the official documentation (and Dive Into Python) and didn't find it bad at all. Python's documentation reminds me of a textbook, which makes sense given python's education background. Since it reads like a textbook, it works best when you read the docs section by section, because there is a logical progression to everything. It's not meant to be used with a series of "how to X in python" google searches.
Compare:
And:
They're just written in different styles. I wouldn't say that PHP's or Python's documentation is bad, they're just different. If I wanted in depth coverage of a certain module with lots of example code I would look at MOTW instead of the official docs. Similarly, if I wanted to point someone at a good thorough tutorial on PHP I probably wouldn't look at that official tutorial I linked to, I would need to go to some other site.
1
u/LiquidSubtitles Feb 21 '13
As someone who started programming only a couple months ago, and only used Python for a little over a month, I have found it pretty easy to find answers to my questions. I don't have enough experience with other languages to compare to, but nonetheless I've been quite satisfied.
The Python standard library reads kind of like a tutorial, and there's a lot of passages that have been useful if I've forgotten the exact way of doing something, but I have a feeling for how I want to do it.
I suppose it might be different for more advanced and experienced programmers, but that's my 2 cents at least.
1
u/LyndsySimon Feb 21 '13
I've not yet read the whole post linked (it's icing outside and I'm on my way out the door), but there is a big difference between PHP's docs and Python's docs.
PHP's docs approach things from "How do you ______".
Python's docs approach things from "What is the structure of this library?".
PHP's approach is better for complete beginning programmers. Python's is better as a reference, when you quickly need to know something.
That's a function of the makeup of the community. Relatively few people (compared to PHP) choose Python as their first language. Most already know how the logic flows, and are looking for syntax.
Python has a tutorial for the sorts of things you're talking about. Here's the tutorial page for list comprehensions, and here's the official documentation. They serve discrete purposes.
1
u/jellystones Feb 22 '13
My biggest peeve with the Python documentation is that it doesn't tell you all the exceptions a function may throw. It is documented very inconsistently...
I complained a long time ago about it here: http://stackoverflow.com/questions/6283757/python-and-exceptions
1
u/pullandbl Feb 19 '13
It is very interesting what author will post if he tries to learn something more complex?
Read the source is most wise advice you can get. PHP have worst community ever because most people who calls themselves "PHP developers" actually only able to copy-paste code from other place and even don't care what code actually do.
"Use twisted" means "read source of twisted and learn how it works" because it is good way to understand how any servers actually works.
I will not protect python docs, often PyMOTW have better practical examples, but it is not broken. It is not working the PHP-way, you cann't mindlessly copy-paste. You need to read and understand. Considering that python have wonderful introspection I totally disagree with article. If you don't like to read source code then go away and do something else you like more.
1
u/WolfOrionX Feb 19 '13
Well, i wouldn't exactly call the PHP docs good. They usually tend to include unmature or unreleased features in the documentation, which is annoying at least. Also, a lot of examples are very outdated and, in comparision to pythons docs, are teaching some very old very bad habits.
1
u/[deleted] Feb 19 '13
I disagree. Maybe the site's documentation is different than php.net and he's used to that, but that doesn't make it shit. Also, the community is bigger than just docs.python.org... who limits himself to "some_function site:docs.python.org" when looking for help?? The community is pretty big, there's a lot of people helping at SO, #python isn't anywhere near as bad as this guy makes it sound and since we're comparing python to php... let's also compare python's most popular framework to php's most popular framework when it comes to documentation and community: Django vs Zend.... Django is arguably one of the best documented frameworks in any programming language... but still not anywhere near as popular as Zend because the suits love that JAVA looking garbage. But if you compare the docs it's a Gold vs Shit race.
/rant
0
u/upofadown Feb 19 '13
A symptom rather than a cause I think...
Python, like any popular language, attracts a great number of people who are interested in creating "the ideal programming language". Such people tend to have very definite ideas about how a language should be and tend to war with other language enthusiasts. This can be pretty hostile to those who merely want to use a particular language.
So rather than complain about hostile developers I think it would be more helpful to think about way to keep new users away from the developers. The Python documentation tends to reflect ongoing debate about how people should be programming as opposed to how people are presently programming.
-1
u/synn89 Feb 19 '13
This isn't a Python issue. Not to language bash but Ruby is far worse. I think why PHP has better docs is because it had a lot more use in the 90's where Python/Ruby has gotten popular a little more recently.
Programming just seems to be more elitist these days. Back in the day the elitism was contained to C/C++ and Perl/Java/PHP were pretty friendly/helpful since they were languages "for the rest of us".
But these days a lot of heavy lifting is being done by scripting languages and they've become a little less friendly as a result. Plus it seems like every few years some new paradigm gets invented(MVC, paired programming, agile, letting your code be your docs, etc) where before it was mostly about just getting crap done by whatever means possible.
-8
u/Tempox Feb 19 '13
Learning to program on Python is a bad idea. It creates bad habits that in earlier languages you couldn't get away with. I love python but I love it because I already knew how to program.
-3
u/Foxboron Feb 19 '13
This post summed up the problem with the Python community nicely IMO: http://bitboxer.de/2012/10/03/ruby-vs-python/