The Python documentation is bad, and you should feel bad.
by admin
Python is quite often hailed as a language that is great to learn programming, due to its simple and often natural-language-like syntax. But there’s one big issue that many Python developers conveniently overlook: the documentation.
While PHP is no doubt a terribly inconsistent language that has some very bad language design, the documentation is, perhaps ironically, very good. It misses some information here and there, and even has some incorrect information in it, but overall it’s a very valuable learning resource – especially for people that are new to programming.
In this article, I’ll go into the most important differences between PHP and Python documentation, and how this is seriously affecting the adoption of Python.
Let’s start out with a simple example. Say you are a developer that just started using PHP, and you want to know how to get the current length of an array. You fire up a browser and Google for “PHP array length site:php.net”. The first result is spot-on, and one minute later, you know that count($arr) will suffice.
Now let’s say that you wish to do the same in Python. In this case, you would Google for “Python list length site:docs.python.org”, and the first result is… a page with several chapters on standard types? It’s entirely unclear how to get the length of a list, and you’ll have to scan through a giant amount of text – even ctrl+F will not help you much here – to figure out this very basic operation. Five to ten minutes later, you know that len(lst) is how to do it.
Note that I have added domain restrictions to both queries, to limit the search to the official documentation – after all, that’s what I am discussing here.
This example immediately shows the first issue with the Python documentation: the organization and resulting Googleability. As opposed to the PHP documentation – which is nicely segmented into separate pages for each function and concept – the Python documentation is written like a book, with chapters and paragraphs. Ever tried to look up the exact point where something happened in a novel? It doesn’t work.
When you Google for something, you will end up on a page that explains a lot of things, including what you’re looking for. But how are you supposed to know where on the page it is, or whether it’s even on the page at all? The problem here is that the particular operation you are trying to find documentation on, does not have its own page.
I frequently bring up the above example in conversations with others about the Python documentation. A common response to that is “but everyone knows how to get the length of a list, that doesn’t need its own page!” But consider this: if the documentation doesn’t explain how to use the language – especially the core components of it! – then what was the purpose of the documentation to start with? The whole point of the documentation is to explain things to people that do not understand them yet. Which brings us to the second issue…
The Python community
Update, February 19: Several people have pointed out that Python developers on Reddit and StackOverflow in particular do not really fit the following section, and I have to agree with that. This section refers primarily to communities that consist mostly of Python developers, and do not have a very distinct culture of their own. The two examples given by others – Reddit and StackOverflow – both have a very distinct and ‘unusual’ atmosphere in general, also outside the Python subreddit/category.
I will no doubt piss off quite a few people with this statement, but the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen – and with that I am not just referring to #python on Freenode, but to communities with a dense population of Python developers in general. This point actually consists of several separate attitudes and issues.
The general norm for the Python community appears to be that if you are not already familiar with the language, you do not deserve help. If you do something in a less-than-optimal way, other Python developers will shout about how horrible you are without bothering to explain much about what you did wrong. When you ask out of curiosity how a certain thing works, and that thing is considered a bad practice, you will get flamed like there’s no tomorrow – even if you had no intention of ever implementing it.
Another issue are the very strong elements of fanboyism around various approaches and particular modules. Try asking any kind of question about sockets, and the standard response will be “use Twisted”. Try explaining why you do not wish to use Twisted, and no matter how valid the reason, the response will be along the lines of “use Twisted anyway”. And it’s not like these are some random people shouting stuff – no-one will even answer the question you asked in the first place, because everyone is too busy telling you to use Twisted.
But one issue in particular bothers me to no end: the assumption that source code is a reasonable replacement for documentation. The documentation on module X is bad? Just read the source. Want to know how the Python interpreter deals with input Y? Read the source. And so on, and so on.
Isn’t the purpose of tools to make your job easier, and less time-consuming? Isn’t the purpose of a higher level language to abstract away the lower level things you do not want to have to worry about? Then how is it acceptable to expect someone to invest large amounts of time into reading the source code of something to understand how to use it?
Would you expect a plumber to know the exact manufacturing process of his wrench?
But perhaps the biggest issue with the Python community is the ostrich mentality. All of the issues mentioned in this article so far – and all those that will be mentioned later on – are conveniently ignored, waved away, or justified by many Python developers whenever they are brought up. The ‘read the source’ mentality is, in fact, often a clear example of this ostrich mentality – instead of working on fixing the documentation, the lack of good documentation is justified by saying that “you can read the source anyway”.
Incomplete documentation
Let’s do an experiment. Think of a random function in a random standard library module in Python, visit its documentation entry, and try to find all the error conditions (return values, exceptions, when they happen, …) without scrolling the page. Didn’t work? That’s not very surprising.
The Python documentation is incomplete. While not always incomplete in the sense of not carrying all the information, it’s very often incomplete in the sense of not carrying information in all the right places. When you go to look up any function in any Python module, standard library or not, you should have an immediate overview of the accepted arguments, the return values, the error conditions, and when these occur.
Again, PHP shines here, having all of the above in a standardized format, for nearly every single function in PHP. To figure out the error conditions for a Python function, you’ll first have to read the function description blurb, then scroll to the top of the chapter, the top of the page, the bottom of the chapter, and the bottom of the page – it may be in any of these places. If you’re very unlucky, the information is not on the page at all, and you have to either Google for it – or even try all permutations of input you can think of, in an interactive shell.
Error handling is important, that is pretty much universally accepted in the Python community. But if error handling is so important, why are you not giving people the tools and information to do so?
The documentation is unclear
Yet another problem. In many cases, the Python documentation is simply unclear. Natural language is ambiguous by nature – many sentences can be interpreted in more than one way. This is an absolutely deadly situation for documentation of a programming language, where you can blow up your entire project by doing one thing wrong.
PHP solves this by having examples for every single function and class. If you’re not sure what is meant with a certain sentence in the description, you just look at one of the included examples, and all ambiguity is removed. It’s immediately obvious how to use things.
In the Python documentation, examples are extremely scarce. If examples are given at all, they are often incomplete, unclear, or lack initialization code or context. More examples are necessary.
Why is all this important?
Now, by the time you’ve reached this point in the article, you may be thinking to yourself: “but I’m doing fine, I have no issues with the documentation as it is, you’re just whining!”
Think about this for a moment. If you are not only reading this article, but you are sufficiently pissed off by it to think something like this – does that not mean that you are already experienced enough not to need solid documentation? If you are an experienced developer, then you are most likely in a very bad position to judge how beginner-friendly the documentation for a language is.
On the one hand, the Python community is trying to actively ‘spread’ the word, and is telling people that Python is ‘so easy to learn’. On the other hand, both the documentation and the community are very newbie-hostile and unhelpful. Don’t you see a problem with this?
If you wish more people would use Python, then start making it possible for them to do so. Restructure the documentation. Think twice about how you respond to a newbie. Respect someones reasons for wanting to do things themselves – as long as you inform them of the associated risks or problems, in an informative manner. Turn Python from a language that pretends to be beginner-friendly, into an actually beginner-friendly language.
Most of all, accept that your personal experiences with Python, as an experienced developer, are not worth very much. Listen to the newbies when they tell you the documentation is hard to read or find stuff in.
No-one is fixing this
Some of these problems are very obvious. Others are less obvious, but still exist. With the amount of issues in the Python documentation and community, you’d expect at least some kind of effort to be underway to fix these… but as far as I can determine, there is not a single person or group of people working on fixing these problems. Why not?
This issue will not solve itself. The only way this issue can be solved, is through a cooperative effort of any Python developer that can spare a few minutes. If even half of the experienced Python developers in the general Python community rewrote the documentation for one function or concept, we would have an absolutely golden documentation in less than a month.
Make it happen. Recognize that it’s broken, and fix it. That’s what developers do.
tl;dr
As this is a tl;dr, it does not include in-depth elaboration and just serves as an overview of the points made in this article. If you’d like to respond to any of these points, please take the time to read the corresponding explanation above first, so you have a complete understanding of the point I am trying to make.
- The Python documentation is not divided into method- or class-specific pages, and as such is very hard to Google through.
- The Python community appears to assume that documentation doesn’t need information about core mechanisms in the language.
- The community is generally unhelpful and hostile (save for Reddit and SO, generally). Beginners are often treated as unworthy of help.
- The community has strong elements of fanboyism (Sockets? Use Twisted!)
- “Read the source” is considered an alternative for documentation.
- The documentation is incomplete (lack of error handling, return value, and parameter information).
- The documentation is ambiguous (very few examples, unclear descriptions).
I complete agree. I’m by no means a python expert, but I know enough to get around, I guess, and I think you’ve hit the nail on the head here. I consult the python docs quite frequently and always have a hard time finding what I’m looking for.
I don’t completely agree (I love the Python community) but I’m presenting a poster at PyCon this year titled “Is Python Newbie Friendly?”. As you might guess I’m tackling some of the issues you raise (and I’ve got some other ones as well).
php might be better, but say the python documentation is bad is a flat out lie. name another language that has better docs, have you even been to docs.python.org?
Have you even read the article?
ruby
Even J# has better docs (btw, I’m a big python fan)
Uh – The PHP documentation is pretty bad, and you should feel pretty bad for even suggesting it’s good.
Then again, I get taken to the exact right piece I “want” to go to with both Python and PHP – through search engines, which almost seems like your main gripe.
I do agree however agree, that the documentation can certainly be improved. Especially when it comes to having a better middle ground between newbie and experienced persons reading.
I would say “how quickly I can get my language-specific question answered” is a pretty good metric for documentation quality. In that sense, PHP docs are extremely effective. It has never taken me more than a few minutes to figure out exactly how do do something in one line of php, or if I just have to implement myself.
This could be inherent to a language that’s basically thousands of global functions, and deviating from core libs is tantamount to torture.
Definitely agree it would help if there were examples everywhere. A lot of the time I’ll use google to go find one after looking at the python docs.
Reblogged this on Stateless Gull..
Hm.
I understand your need to measure the length of a list quickly, but you should really spend this 10 min to read all the characters on basic data types. It might be non-intuitive coming from the PHP background (where nothing makes sense and there is a function for everything with an obscure name), but this is not really a very good approach. Python documentation is good, but focuses more on understanding than on quick answers. On the other hand, #python is notoriously hostile (I don’t even bother hanging out there).
The PHP documentation is standarised in a particular format, as is Python. It does not mean the PHP documentation style is good for Python, it’s good for PHP. Python documentation is good for Python. I understand the problem of “Python documentation for PHP programmers”, but there is nothing like that. Personally I like the Python documentation better (although I would not like Python-style documentation for PHP, it would make no sense).
Cheers,
fijal
PS. find me as fijal on IRC if you want to discuss
As someone who began to learn Python quite recently, I completely agree with you. The official Python documentation is very… boring. I had to read trough lots of things that I already know or I’m not interested in for the time being.
It was a challenge to learn Python from scratch, most of the things I’ve learned were by searching questions on Stackoverflow and reading the comments.
I do concur with your critique of the format of Python documentation. I’ve always disliked they way I have to read and parse several paragraphs to find a reference to parameter. It should be up front in table format so I can see at-a-glance each parameter and what it does.
Not sure I agree about searchability though. Most often Google gives me the correct answer from the first result. Admittedly, it’s not always from the official docs, since I don’t filter by domain — but I don’t particularly care where the answer comes from.
You are dead wrong when it comes to the Python community. I’ve always found Pythonistas to be a very helpful bunch, who fall over themselves to help you. Personally, I try to do the same.
I wouldn’t be surprised if you get a few unhelpful responses, but I suspect your negative opinion of the Python community is a self fulfilling prophecy. If your tone is overly critical or hostile — and in reading this post that wouldn’t surprise me — then you will get fewer helpful responses. Nothing to do with Python, it’s just human nature.
I think your post hits with my own views the best. I learned Python from a combination of the docs and an old version of “Learning Python.” I think the details are there if you spend the time, and the extra investment of reading through can be worth it. There could be plenty of room for improvement there though to make it more readable, segment it in a way that’s intuitive to newbies and old-hats, etc.
The one thing I’d like to add to what you said is that I could believe that the docs could be improved in their descriptions for newbies, but I’m not sure they should be. I consider Python a great language for a new programmer, but the docs aren’t a great way to learn the language for a newbie – books are. They were helpful to me as someone who understood programming concepts from other languages, but when I think of someone brand new, I’m not sure it would help. Still, I think they fill the role of documenting the language well, and the role of using it and putting it all together is better left to books (where Mark Lutz has done a great job, in my opinion). Just my two cents.
If you want to learn Python, just read this http://geosci.uchicago.edu/~rtp1/PythonSupport/PythonNotes.pdf
thanks for the post
I’ve got similar feelings re Python documentation (even though I’m quite experienced in programming using java)
I picked up Python as my first language after not having coded in 25 years. I agree that the documentation is bad. I often have to look up several examples in Google to pair with the confusing documentation in order to grasp some concepts properly. I don’t agree with the statements about the community around Python… or maybe my scope is just limited. I found so much valuable help from places like Stack Overflow and Reddit. I rarely encountered anything even close to the attitudes you described. People not only answered my questions, they often provided much more insight to my problems than I would have gathered from the sterile docs.
I do have to point out – and probably should have done so in my article – that Reddit and StackOverflow are two notable examples of a different ‘attitude’, than most of the rest of the Python community (forums, IRC channels, mailing lists, etc.). However, I do believe that has more to do with the general atmosphere on Reddit and SO, than with the Python community itself.
I got bored of reading half way through, because to be frank: this article is bad and you should feel bad.
> Make it happen. Recognize that it’s broken, and fix it. That’s what developers do.
Go fix it yourself then, lazy bastard. That’s what open source does.
Have you considered that I may simply not have the time or knowledge to rewrite the docs? Something like rewriting documentation is a gigantic task that can only be undertaken in a collective manner – no single person could be expected to rewrite all of the Python documentation into a different format.
Your response serves as nothing but a way to deflect away from the problem. Additionally, it’s probably a good idea to look into what someone spends his time on, before calling him a “lazy bastard”. Something about ignorance and premature judgment…
But you’ve called to:
“This issue will not solve itself. The only way this issue can be solved, is through a cooperative effort of any Python developer that can spare a few minutes. If even half of the experienced Python developers in the general Python community rewrote the documentation for one function or concept”
So, do it for an example function/concept. Show them/us the improve, how bad it was and how good it can be.
You said, it’s just: “spare a few minutes”.
That’s a fair thing to expect. I’ll publish an example soon.
Spoken like a true Python dev.
Spoken like someone who makes plenty of assumptions.
Agree, it should be broken into smaller more specific chunks. I tend to go to stackoverflow more often and avoid the docs.python results because I now I have to do a lot of scanning and searching to find the actual answer.
But never had a problem with python community and I think your comments (both offense and defense) detract from your first premise.
Also your post is about 2ft too long, just like the docs
I didn’t read your whole post either.
I have added a tl;dr at the bottom of the post
I very much agree with this – while I’m an experience python developer now, trying to find information on parts of the language itself was very annoying when I was learning, and I really missed the PHP documentation.
I think this idea that there really even is a Python “community”, in some a kind of false dichotomy because it’s so varied. There’s a scientific community, there’s a jython community, pypy, irc, stackoverflow, linkedin, etc. And they all act a little differently in my opinion.
The “Just use Twisted thing” is mostly a #python on freenode IRC because thats where the developers of Twisted have always hung out. However, if you go on stack overflow or linkedin or somewhere else, you’ll usually get a more “noob-friendly” answer.
IRC is that way in general. Try going in #bash and asking a noob bash question. Try going in #vim and asking a noob vim question, etc. There are experts who have been there for well over a decade who have refined the learning process down to a sort of customer-service like script. This is to handle the large number of questions that are asked on a daily basis. And it’s also because of how terribly some of the questions are asked.
As for the documentation being bad. I don’t think it is. It’s just different. Python as a language IS very noob friendly because it’s so easy to read and play around with (spawn a REPL in one command; spawn a web server in one command and so on).
Python has a lot of idioms and conventions so you will often be told that your ‘way’ of doing things isn’t the python way. But it’s not strictly enforced. Yes, we have PEP8 but myself and a lot of others in #python have been using Python since well before PEP8 and don’t necessarily agree with everything. Also, try asking an advanced-ish question in the PHP community and getting an answer — it rarely happens. Whereas in the Python community you’re dealing with a great many talented software engineers, not just web scripters (not that there aren’t a few in the PHP world, but they’re way harder to come by).
I’ve done Python and php for over 10 years and the bottom line is I rarely need the Python documentation anyway. I do need PHP docs all the time when working with it because the language is such a mess and all it really is is one giant list of functions in the global scope for the most part — which makes it as easy as typing http://php.net/function-name to find anything. But that hardly makes python documentation poor.
Just my opinions. Now go use Twisted and RTFM.
Apparently there’s as many opinions as there are people. How surprising. But okay, let’s move past the that. A few years ago, i was a newbie. Not only to Python, but to programming as well. Single most useful resource for learning Python? The docs. Now, I should mention I learned PHP at around the same time as Python (next semester, to be precise, so a couple months apart), and I remember its documentation as very good – for PHP. A language that makes no sense. So I was very happy to have every single function explained to me like I was five. For Python, I didn’t *need* this. I had the same reaction as you when I first looked at Python documentation, but that reaction changed very quickly, and whenever I try searching for something on my local copy or on the web, I always find it. It’s just organised in a different way, from a different mindset, and once you wrap your head around Python, this mindset become second nature.
I’m not sure what other communities you mean – for instance, the people over at /r/Python are a friendly bunch, while, in my experience at least, the fucktards that always go “use Twisted anyway” are all confined to Freenode’s #python. Don’t worry, no one likes them. (And I should mention that the “use X anyway” line is fo’ real, yo – these people are a little….lopsided.)
python.org >> “DOCUMENTATION” >> “Current Docs” >> “Tutorial (start here)” >> “3. An Informal Introduction to Python” >> ctrl+f “length”
I intuitively walked that path after having used Python and its website for many years. However, I believe that a newer user, encouraged to have faith in the documentation, should have no problem following a similar path.
That said, what was your responsibility to have read the language’s introductory documentation? You would have learned about the unique way Python handles length measurements early on and been fast on your way to learn the Zen of it all.
Look it up. Good luck on your travels.
You want API documentation like PHP? We’ve got that. They’re called docstrings. We’ve also got a help() function that will spit out docstrings, and myriad REPLs and editor add-ons that will put them right in your face whenever you need them.
You want *actual knowledge* about something, like the concept of “the length of something”? We’ve got narrative documentation for that. Oh, and a tutorial. And a ton of supplementary material. I clicked on the count() link for PHP: now I know that it gives an array length, and “something on an object” if I have SPL installed (guess I should Google for that… just more API docs).
You want a community of surly folks to make you explain *why* you want to do something before telling you *how*? We’ve got IRC. And, as a general gauge of hostility, IRC is always a terrible data point regardless of the community.
None of that helped? Still not sure what the return value of something is? Look at the source. Telling you to do that doesn’t make me an ostrich, it just makes me a programmer. If I stopped to complain every time I had to read a little Python because a library author didn’t describe every function in a detailed docstring, I’d never get any work done. I may not like that they don’t and I certainly do my best to in my own code, but it’s hardly a recommendation I should feel *badly* about.
Hi my advice is in the same line.
I don’t have this perception of Python community, because usually I just use the shell for this kind of doubts.
You don’t have a similar one in PHP, so you weren’t used to think on this possibility
How to get simple help as the mentioned on this post.
1. Install ipython — pip install ipython (on Linux)
2. Get used to try small code snippets on the shell
$ ipython
In [1]: people = ['me', 'you']
In [2]: people. TAB TAB
people.append people.extend people.insert people.remove people.sort
people.count people.index people.pop people.reverse
In [2]: people.count()
—————————————————————————
TypeError Traceback (most recent call last)
/Users/luciano/src/warehouse/ in ()
—-> 1 people.count()
TypeError: count() takes exactly one argument (0 given)
In [3]: people.count??
In [3]: people.count??
Type: builtin_function_or_method
Base Class:
String Form:
Namespace: Interactive
Docstring: L.count(value) -> integer — return number of occurrences of value
## I know, in this example, you don’t know how to get len() yet.
But http://docs.python.org/2.7/ has an indication “start here”, which is subtle, but this means, “New to Python!? Come this way, let’s cover the basics.”
I find it difficult to take the author seriousely when he tars the Python community with the statement:
“I will no doubt piss off quite a few people with this statement, but the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen – and with that I am not just referring to #python on Freenode, but to communities with a dense population of Python developers in general.”
Ah, hell. I’ve got to do something positive.
To the original author, maybe there is an impedance missmatch between how you want to learn and the Python resources you have googled? A lot of people learn Python through the resources available. It is not the way PHP does things, but is good for Python. When learning a new language the hardest part can be remembering the flexibility needed *to* learn.
Python documentation is a continuing process it does get better over time, but equally you may need to bend to the teaching methods available as well as lament that past PHP documentation skills are not as effective in Python.
A good way to learn Python is to start by reading and doing the exercises in the tutorial. That usually gives enough context to better phrase subsequent searches. The documentation is browsable so get to know what is in the Library Reference too. I guess The docs go more for a “composable” style rather than a cookbook of recipes on how to do every little thing you get the ingredients and how to best use them together.
I want! I want! Meet the real world
I’ll concede the formatting issues on the documentation. It could be better… but overall, my experience in learning and using Python over the past 12+ years doesn’t seem to match yours at all. In summary, Python has changed my life for the better… I enjoy programming again and I’m thankful every day for the effort of the thousands of people who continue to make it better. I can’t say the same for PHP or any other language.
“The Python documentation is not divided into method- or class-specific pages, and as such is very hard to Google through.”
True. This is partly because the documentation has been around in the current format for a long time. The documentation was always very good and is still good, but yes, the “googlability” is not that great.
But claiming it’s bad isn’t true. You claim that searching on the page won’t help much in your example, which is completely false. Search for “length” and you will soon come to the method len() with docs saying it returns the length. Done.
Search for “length” in the PHP page you end up with, and the only thing that tells you that count() is what you are looking for is a code example in the comments.
Sorry, that does not make the PHP documentation any better of more googlable that the Python documentation. Your example contradicts your statement.
But yes, splitting up the documentation makes it more googlable, but also less readable. It’s not obvious which is the correct solution.
“The Python community appears to assume that documentation doesn’t need information about core mechanisms in the language.”
A very strange and in my opinion directly false statement.
“The community is generally unhelpful and hostile (save for Reddit and SO, generally). Beginners are often treated as unworthy of help.”
True for #python (and #django, but that’s not core Python which we are talking about here). Otherwise completely false. Reddit and SO are not the exceptions #freenode is.
“The community has strong elements of fanboyism (Sockets? Use Twisted!)”
Complete bullshit. Yes, yes, there are tons of fanboys. But there are fanboys of everything, not just twisted, but of all the alternatives. It’s called “religious wars” and every community has it. Pythons wars are generally quite friendly.
““Read the source” is considered an alternative for documentation.”
Much more than in other communities, yes. This is because Python is so eminently readable, that it is in fact a useful suggestion. This probably comes as a shock to people in other programming language communities. But, yes. In Python, reading the source is often a good idea.
I recently found a bug and submitted a patch in Django’s templateing system, about half an hour after I first ever looked at the source code for Django templates. I’ve tried that with other languages, I generally give up quite quickly.
“The documentation is incomplete (lack of error handling, return value, and parameter information).”
No, it’s not incomplete, but yes, a standardized format for that information would be an improvement.
“The documentation is ambiguous (very few examples, unclear descriptions).”
Unclear descriptions, no. Few examples, yes.
So in all, what are you correct about:
* Yes, Python documentation comes in bug chunks. For good and bad.
* Yes, it needs more examples.
* Yes, a standardized format for parameters and return values might be a good idea.
Does that make the Python docs bad? No.
“But claiming it’s bad isn’t true. You claim that searching on the page won’t help much in your example, which is completely false. Search for “length” and you will soon come to the method len() with docs saying it returns the length. Done.”
Depending on your programming style, you may have to look up reference for things very often (say, every few minutes). This turns what you present as a ‘minor inconvenience’, into an absolutely intolerable situation as it becomes more and more time-consuming and frustrating.
“Search for “length” in the PHP page you end up with, and the only thing that tells you that count() is what you are looking for is a code example in the comments.”
I’m not quite sure why you’re trying to make this comparison – why would you try to search for ‘length’ on the PHP page in the first place? It’s already in your view – there’s no need to work around the mess by searching for ‘length’.
“But yes, splitting up the documentation makes it more googlable, but also less readable. ”
I have not seen any supporting evidence for splitting up the documentation making things less readable.
“True for #python (and #django, but that’s not core Python which we are talking about here). Otherwise completely false. Reddit and SO are not the exceptions #freenode is.”
My experiences are very different. Whenever I visit any Python-developer-dense IRC channel, read pretty much any archived Python mailing list or Python-related forum… I run across the same kind of behaviour towards the same kind of questions or voiced complaints. This is not just isolated to Freenode.
“Complete bullshit. Yes, yes, there are tons of fanboys. But there are fanboys of everything, not just twisted, but of all the alternatives. It’s called “religious wars” and every community has it. Pythons wars are generally quite friendly.”
I don’t really care how ‘friendly’ or ‘hostile’ the ‘religious wars’ are – the reality is that it prevents people from getting answers to their questions in the case of the Python community. And again, not just on Freenode. It’s a serious roadblock.
“Much more than in other communities, yes. This is because Python is so eminently readable, that it is in fact a useful suggestion. This probably comes as a shock to people in other programming language communities. But, yes. In Python, reading the source is often a good idea.
I recently found a bug and submitted a patch in Django’s templateing system, about half an hour after I first ever looked at the source code for Django templates. I’ve tried that with other languages, I generally give up quite quickly.”
You are confusing two *significantly* different things here – code documentation and usage documentation. While ‘read the source’ is fine if the source is what you’re trying to edit/improve/fix/understand, it’s absolutely unacceptable when you’re trying to use it as a black box that just has to work because you need to get this stuff done *right now*.
Suggesting that reading the source is an acceptable method of understanding a library that you’re just trying to use as-is, is akin to telling an architect that he should understand the manufacturing process about all the materials he’s using and figure out specs for himself, because there are no specifications readily available.
“No, it’s not incomplete, but yes, a standardized format for that information would be an improvement.”
Then mind explaining why there are things that the documentation simply does not explain, if it’s not incomplete? (“This error condition can be caused by such and such.”)
“Unclear descriptions, no. Few examples, yes.”
I have had issues with ambiguous descriptions in the Python documentation more than once. So have many others that I have talked to. That you *personally* can guess what is meant, does not mean that it’s equally crystal clear or obvious for everyone else.
The fact that people do have issues with this, regardless of whether *you* have issues with it, is an indication that it is a problem.
I have look up things very often, and this is not a problem with the pthon docs. But something that also makes a difference in how often you have to look things up is the language, and if it is consistent or not. With PHP you have to look up every cal you make all the time because none of them makes any logical sense based on other calls. This is not the case with Python.
Also with even remotely good developers tools, half the time your editor/IDE will tell you what the available parameters are, and you can click to definition to see the function definition or the list of fuctions.
“It’s already in your view”
No it’s not. The first result is http://php.net/manual/en/function.array.php Maybe you get http://php.net/manual/en/function.count.php first because you have clicked on it many times, which you again have done because you know what you are searching for.
With your Python search, the first result is the built-in functions. http://docs.python.org/2/library/functions.html Which is the correct page.
“I have not seen any supporting evidence for splitting up the documentation making things less readable.”
So you think it’s easy to read documentation when you have to jump back and forth between different pages? You don’t need to “see supporting evidence” for that that it makes it less readable, it’s completely self-evident. As pointed out by others here, the Python documentation doesn’t just list functions with their parameters and results, but it gives you and overview of the module and an explanation of how to use it. Athough, as you point out, it’s low on examples.
“the reality is that it prevents people from getting answers to their questions in the case of the Python community. And again, not just on Freenode.”
It’s not just freenode, it’s specifically #python, which you somehow has gotten confused with the “Python community”. It does not prevent people from getting answers, and it’s even on #python no worse than in any other language community. This claim from your side is complete and utter bollocks, the end. I have, during my 12 years in the Python community, not seen “use twisted” as an answer to anything at least since like 2005. There are a lot of alternatives to twisted that are popular and just as hyped as twisted.
“You are confusing two *significantly* different things here – code documentation and usage documentation. ”
Nobody tells you to “read the source” for basic usage documentation in Python the language or the standard library.
“Then mind explaining why there are things that the documentation simply does not explain, if it’s not incomplete?”
That is a completely bizarre question. Are you claiming that the PHP documentation explains exactly *everything*? That there are no flawes, misses or forgotten things in the PHP documentation? That everything in the PHP documentation is crystal clear with no ambiguities or possibilities for misunderstanding? No of course you are not, that would be stupid.
Are you claiming that the Python documentation as a generality do not explain how to use functions and methods? That’s utter and complete bullshit, so I hope that’s not what you are saying.
Again, you are expecting the Python documentation to be as clear to you, who do not know Python, as the PHP documentation is to you, after years as a PHP developer. That’s not gonna happen.
When I look at the PHP documentation, I see loads of things that are unclear and confusing, and I find it hard to get an overview and an understanding of the language and it’s functions and libraries.
Because I’m not a PHP programmer.
You expect the Python documentation to be as usable to use as a PHP programmer as the PHP documentation is to you as a HP programmer. It isn’t. It is however as usable to me as a Python programmer as the PHP documentation is to you as a PHP programmer. And once you have become a Python programmer, it will be to you as well.
I think the documentation for Python is one of the best I have read. Why do I think that?
Because it has both a high-level overview of the language and functions, modules and classes and also an API documentation for everything.
Why I loathe the doumentation of.. lets say Ruby and Ruby on Rails(why I have been using at work for over 4 years) is that it’s basically a mess of javadoc style API descriptions, with some guides scattered accross the web. It’s sometimes difficult to get the big picture on how all the little functions should be used together.
Python on the other hand has all the docs in one place for the core language, it’s easy to navigate and most of the modules and classes come with examples on how to use them. Also there’s the excellent PyMOTW project. Other Python libraries also tend to have great documentations. SQLAlchemy for example.
Python’s docs should be set as an example for other languages to strive to.
The author’s only argument seems to be that “I can’t find the correct answer as the first result on google, I may have to read some paragraphs of text before getting to the answer
“… is bollocks.
It would be awful if the python documentation would be formated like the PHP docs are – all functions each on their own page. PHP docs are like this because PHP consists of a bunch of functions cobbled together.
I felt I had to comment on the first point you made about getting the length of a list or array.
Personally, I hardly ever use site:… in my google queries, and as it’s extra work and it requires you to know this syntax I doubt most people learning a language would.
The first hit for python list length gives me all I need.
Granted, your post is about documentation, so maybe you would argue that you need a link to the documentation to show up. But with such generic search terms (that just also happen to be programming terms) it’s pretty normal for google to turn up places that include the verb ‘lists’.
Even so, item 2 on your search query shows in the abstract: “Return the length (the number of items) of an object.” So Google did find the right location, it’s just too bad that when you click on it, you get to the start of the section and you have to look for length in the page. Still very easy to find though.
It feels like a contrived argument to argue that the docs are bad. Sure, they could be improved, but you picked one of the worst examples to focus on.
I also don’t understand why you find it ironic that the PHP docs are so ‘good’. They kind of have to be no if you want to get anything done in PHP?
Regarding the filtering by site:docs.python.org, I’ll quote my response on the corresponding Reddit thread:
“My point was that the official Python documentation is poor. I certainly agree that many things are answered on StackOverflow, but imagine that you’re looking for something that not very many people use.
You’ll search on Google, not find any StackOverflow posts (after all, nearly noone uses the thing you’re looking for), and you just find a few unclear blog posts and a Python documentation page.
Official documentation is important especially as a fallback when other sources fail to provide the relevant information. As such, the focus of the official documentation should be on complete and clear, unambiguous reference. That’s not what the official Python documentation provides.
While len() may be a very simple example (and intentionally chosen for that reason), I’ve more than once run across things for which basically no documentation could be found aside from an ambiguous explanation in the Python documentation that never got me anywhere.”
Regarding “having to look for it on the page” – having to do this every few minutes to look up some kind of reference quickly gets time-consuming and very annoying. While you paint it as a ‘minor inconvenience’, it occurs so much for certain styles of programming that it’s absolutely intolerable.
I just love python but I completely agree with the article.
Sheer unadulterated rubbish.
In fact, if you google for: Python list length , the first hit gives you the right answer. It’s telling that you did not use a better example. Don’t restrict your search to docs.python.org – why in the world would you? The very reason some parts of docs.python.org are not very google-friendly is because this need is already filled by some other sites. When I google for any python question, I never restrict results to any site, and in 98% of cases I find what I need very easily.
TLDR: don’t sabotage your google search and you’ll have nothing to complain about.
It helps if you actually read the rest of the comments, because I’ve already explained in these comments *and* on Reddit why I am filtering by docs.python.org.
http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/#comment-151
Thanks for the nice writeup of the problems with Python’s docs. I might quibble with a couple details but by and large I think you described the problems very well. As always, such critisisms produce an almost biological immune reaction as the Python-borg reacts to defend itself from the threat.
One issue not often mentioned is what changes will be accepted by the developers who have the most influence and control over the documentation. Some of them have publically expressed the sentiment that the docs have grown too large. Since some of the complaints about the documentation are excessive terseness, not enough examples, unstructured formatting (no section per function/class etc), a controlling attitude that limits increases in size will obviously limit such improvements.
I posted my take on the Python Docs problem to the python general mailing list (mirrored to usenet comp.lang.python) which includes another specific example (like your “length” experiment) and also a set of rebuttals to many of the defenses of the Python docs seen in these comments.
http://mail.python.org/pipermail/python-list/2013-February/641750.html
Python – seems like a fun language, but the documentation is terrible.
Comparison with PHP makes no sense, because PHP have a great documentation.
I started to learn Python a while ago, and when I saw the documentation first time I couldn’t comprehend it. I was looking around the page, to find “the real thing”.
Lets see this on the simple example, – string.replace function in various languages:
Python: http://docs.python.org/2/library/stdtypes.html?highlight=replace#str.replace
Buried deeply in the “Built-in Types” page, surrounded with a lot of irrelevant bullshit. Two lines, brief explanation, no examples. Little-to-no styling of page makes it even harder to find it, plus, it makes hard to quickly find relevant information in the description (like the return value, etc…)
No way of finding it if you don’t slowly scan the whole page or use F3.
—–
PHP: http://php.net/manual/en/function.str-replace.php
On its own dedicated page, each parameter and return value very well explained, there’s also change log, examples, useful notes, related functions, and finally more or less useful comments.
But look at the design of the page also, it’s so easy to quickly scan through it… That’s the point, – documentation isn’t the book, documentation isn’t tutorial, – tutorial is tutorial, book is book and documentation is documentation. All of them serving different purposes. Documentation will also be the source of information for people who are already familiar with many concepts of the language. Perhaps someone just need to know what’s the third parameter particular method will accept.
—–
Java: http://docs.oracle.com/javase/1.4.2/docs/api/java/lang/String.html#replace(char, char)
Fairly easy to find (at the top of the page there’s a link to “replace” method), couple of lines of description, example, easy to read description of each parameter, and return value.
—–
C++: http://www.cplusplus.com/reference/string/string/replace/
Like with PHP, on its own dedicated page, each parameter and return value very well explained, examples, useful notes, related functions.
—–
Ruby: http://www.ruby-doc.org/core-2.0/String.html#method-i-replace
Easy to find (there’s link in sidebar, together with related methods), in general page is designed well – it’s very readable. Short description is offered, together with an example and source code which you can examine on the page. If Python community feels so enthusiastic about people read the source code, why not to offer at least such feature?
—–
Finally even(!) JavaScript, on: http://www.w3schools.com/jsref/jsref_replace.asp
Examples, description, each parameter and return value clearly and very well explained (additionally specific for JS browser support and chance to try it yourself online).
—–
Now, for the love of God, stop defending this pile of shit you call documentation and please, please, please, those in power to do so, make moves, that I’ll get fixed; if nothing else, it will help if you’l finally admit that it’s terrible, and need various fixes.
Apologies for typos…
Quote:
“”"
The general norm for the Python community appears to be that if you are not already familiar with the language, you do not deserve help. If you do something in a less-than-optimal way, other Python developers will shout about how horrible you are without bothering to explain much about what you did wrong. When you ask out of curiosity how a certain thing works, and that thing is considered a bad practice, you will get flamed like there’s no tomorrow – even if you had no intention of ever implementing it.
“”"
Bang on!
I am an amateur coder and use, and have used, Python in non-standard ways and eventually joined a Python ML, (a well known one), with a couple of give away snippets, (now on code.activestate.com). I was immidiately belittled which took me by complete surprise. I have no idea why as not one of them asked whether I was a professional and was at a computer coding for a living or just able to get to a computer in my own time… The latter is the case.
After a few months I unsubscribed as the hostility and rdicule to some, myself included, was too much for me and went back to my unusual coding techniques in my own time…
I really learnt little or nothing from this ML and now learn by trial and error it is much easier…
73…
Bazza, G0LCU…
Bazza, I’ve now looked through your posts on python-list, and it seems that your last posts was in the thread “An unusual question” where you asked how you could run machine code directly from within Python, and the answers were on the line of “You can’t, at least not without major hackery and trickery, which you as a newbie are highly unlikely to be able to be capable of, and even if you could it wouldn’t be worth it.” Apparently you took this truthful statement as some sort of insult and left. However, none of the comments were particularily rude and none of them were hostile or belittling in any way.
Not getting the answer you hoped for is not hostility or ridicule.
Actually, I missed one of your answers, and it’s worse than that. What you do is saying “I have done X, now how do I make Y”, and when you get the question “What do you mean with X, how would you do X, this won’t work, and if you have to ask these questions you won’t make it work”, to which you respond by agression, attacks and refusing to answer the question of “how would you do that” with “why should I reveal that secret”.
The only one unfriendly and belittling in that thread is you, Bazza.
OK, one last thing: http://thisispycon.com/post/46752625176/python-had-always-been-on-my-list-of-languages-to#_=_
Just sayin’.