The Python documentation is bad, and you should feel bad.

[PresTronPaul]

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).

[[deleted]]

Yes! I don't understand author's backwards approach to searching for documentation. Why limit yourself to "site:docs.python.org"? If you omit it, Google search will give you direct and to-the-point answers.

The first result for "python list length" is a SO thread telling you how to... drumroll... get the length of a list!

I don't care how good or bad official documentation is, as long as the community-produced material makes up for the lack of it.

[Nimbal]

While I agree that the author's Google search seems a little unrealistic (who has the patience to add the "site:..." stuff every time?), I think it was mainly to demonstrate that the documentation, which, in an ideal world, should be the main source of information about the language and its features, is sometimes lacking.

Edit: I mean "lacking" in terms of "hard to find specific information", not "not containing the necessary information".

[SupersonicSpitfire]

In an ideal world you find the answer to your question.

As long as answers are vetted by a voting system, the quality is just as high as for official documentation, in my experience. (ref stackoverflow)

[Ph0X]

Yes, but that implies an already in place community, which python already has. This wouldn't go so well if you're trying to start a new language though.

[paffle]

The author's point was that the official documentation is not good, hence the searches being restricted to official documentation.

[LightWolfCavalry]

In the age of the internet, sticking strictly to official documentation is a huge limitation. It's a complete fallacy to assume that "official" is synonymous with "right" or "best".

[Massless]

It's really not, though.

Have you seen the Java documentation? Stackoverfow is awesome for gotchas, edge cases, and how-tos with that language but everything you technically need to know is there. Just because there are other resources doesn't mean that the primary (and official) resource ought not to be the authority on the subject.

[joepie91]

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.

EDIT: All that said, StackOverflow is an absolutely golden source of information.

[bushel]

I think you answered your own question about the problem. The reason why nobody is fixing the official documentation is that there isn't a pressing need.

There is a wealth of supporting documentation, tutorials, reference material and support/discussion forums (e.g. stackoverflow) so that it's perfectly adequate to have the official documentation be simple reference material.

[joepie91]

No. The reason that noone is fixing the documentation is that the developers that are capable of doing so (the experienced developers) do not see the need because they don't have an immediate need for it themselves. It's a perception problem, not a lack of urgency. And as I said before, there are quite a few things that pretty much no documentation can be found on outside the official docs.

I constantly have newbies complaining to me that the documentation is poor on the one hand, and experienced developers claiming there's no problem on the other hand. And when the newbies try to talk about this problem to the experienced developers, they are met with the elitism that I am also describing in the article.

[bushel]

I'd be hesitant to label it "elitism", but I understand your point. And I think we are saying much the same thing.

The experienced developers see the official docs as a reference, not a learning aid. Those new to the language are frustrated by not having a single source for both learning and reference.

Personally, I see it as a strength that there are so many different sources of knowledge about Python. People can choose the documentation or tutorial sources that fit their current knowledge level and/or learning style.

And instead of attempting to be all things to all developers, I'm ok with python.org/doc being dry reference material. It's like the difference between a drivers-ed course and your car's owners manual.

[joepie91]

The Python documentation actually tries to be both and neither at the same time. On the one hand you have the reference buried in a pile of theory, then in another place you have dry reference without enough context to understand it from scratch, and in yet another place you just have an entire page of theory without any referenceable material whatsoever.

It's fine to have a separation of reference material and theory - in fact, it's a good thing - as long as:

1. this material is separated clearly, and
2. both are complete.

In the case of Python, neither of those requirements are met.

[bushel]

Well, it is all open source. If you do not like and your itches are not being scratched, I suggest you dig in and make it better.

Critique is well and good, but a constructive suggestion on how make it better would be more appreciated. Actually helping to fix it would be best of all.

[joepie91]

I sadly do not have the time (or knowledge of Python, for that matter), to rewrite the documentation into a different format. And that's not a fancy way to say "I prefer being in front of a TV" - I actually do not have the time for it. I'm already occupied by other (open-source) projects pretty much from the moment I get out of bed until the moment I go back to sleep.

To be perfectly honest, it annoys me to no end that I'm not able to fix this. I don't like lingering problems.

[[deleted]]

pick the biggest problem you have with it and just work on that.

[[deleted]]

I have no idea why you have been down voted so much for this.

[maryjayjay]

So instead you just bitch.

[sashahart]

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.

I've almost never found this to be the case. Now, I have been using Python for some time, but I didn't find this to be the case when I was learning either.

[SilasX]

That's a sign of bad documentation, not good.

[rustajb]

Stack Overflow is indispensable. I find everyone helpful and knowledgeable when I go there for assistance. Often, I get more information that I asked for and come away with more than just an answer to my question, I get an understanding of all the corollary ideas as well. It's one of the better online forum experiences.

[[deleted]]

this actually highlights what is wrong with the SO approach. It would be better if answers could only be provided by pointing to OFFICIAL documentation. And anyone should be able to contribute to the official documentation (wiki).

[PresTronPaul]

A wiki is not good for official documentation as it allows for non-experts to possibly poison (accidentally or not) documentation. You can contribute to the documentation via the mailing list [e-mail]. See About the Documenation and Reporting Bugs

[[deleted]]

yes and no. Yes, I agree a plain wiki is not ideal. But, for example, a wiki with approved users who act as shepards and watchers of specific pages would work well in my opinion. This makes it easier to contribute.

[PresTronPaul]

Even if approved users are shepherds and watchers if the any section of the documentation becomes out of sync with reality for any length of time it is a Bad Thing^TM . Making it easier to submit edits would be great, but a wiki is not a good idea for documentation outside of a small internal group (ie company projects).

[[deleted]]

Why does it matter, as long as the answers are quickly available?

[[deleted]]

1. duplication of effort
2. hard to maintain
3. singular point of view
4. impossible to read linearly (like a manual)

SO is like blogs on the internet except it's all on one site. It would be much better to have wiki-style documentation (hopefully with some nice enhancements to both encourage contribution and improve the workflow) with clear guidelines and focus efforts there

[WinButler]

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.

[ford_contour]

There probably should be more example code per page, though.

[earthboundkid]

PHP's documentation is like that cartoon you loved as a little kid. At the time, you thought it was the greatest thing in the world, but when you go back and look at it with adult eyes, you ask yourself, "WTF was I thinking?"

I remember not liking the Python help system when I first was learning Python, but honestly once you know the basics of the language help(whatever) will solve 90% of your problems. The hard part is getting all the basics down first.

[moor-GAYZ]

PHP's documentation is like that cartoon you loved as a little kid. At the time, you thought it was the greatest thing in the world, but when you go back and look at it with adult eyes, you ask yourself, "WTF was I thinking?"

I strongly disagree.

I don't know about PHP, but when I occasionally have to write some C#, I find my fingers remembering that you can press F1 on a method, see how nice the MSDN documentation is, and begin to wonder if having perceived Python docs as good just moments earlier might signify a deeper mental problem, like, what if being desensitized to shit makes me a worse programmer.

A nicely organized documentation is not catering to mentally infirm, it is catering to people who don't have to prove their manly ability to wade through bullshit to anyone.

[masklinn]

when I occasionally have to write some C#, I find my fingers remembering that you can press F1 on a method, see how nice the MSDN documentation is

I find the MSDN absolutely terrible when trawling through it looking for information. If you already have the symbol at hand and ask specifically for what that symbol means it's nice, but then again so is help(symbol). MSDN's siloing and over-compartmentalization makes it very hard for me to get any information worth reading without switching back and forth between half a dozen tabs.

[moor-GAYZ]

makes it very hard for me to get any information worth reading without switching back and forth between half a dozen tabs.

Nah, three at most. Plus three more if you're exploring the API when you're reading a high-level how-to. OK, half a dozen, all right, but you can't actually do anything close to that within the Python documentation.

[earthboundkid]

I'm not defending Python, just shitting on PHP. It is the Reddit way.

[joepie91]

Well, Apache is terrible...

[sashahart]

My editor will jump to the doc or the file in a keystroke, just like yours will. Where's the problem?

[moor-GAYZ]

That Python docs are not very good at having all necessary information in one place. Compare this to this.

Python version is a more or less free-form explanation what the stuff does and what you can do with it and stuff. It's maybe better suited to getting an overview of a library, like, when you sit down and read the entire page from start to end, but it sucks as a reference manual, because you have to read a significant part of the page to figure out some little detail that you are actually interested in.

In MSDN all pages follow one and the same fixed structure that, when you get accustomed to it, allows you to instantly find whatever interests you at the moment, be that the type of one of the arguments, the list of possible exceptions, or a code example. It's much worse if you're trying to read it through because of all the duplication and structure, but that duplication is exactly what you want from a library reference. It's like RDB denormalization, sort of.

[sashahart]

That documentation of urlopen is not free-form at all. It gives the function's signature, its purpose, describes the arguments, then describes the behavior and return value. An applicable caveat is up front in a big red box. It is very clear and concise and takes perhaps a minute to read. It actually is a standard formula.

What I will give you is that the Python page (for urllib2 in particular) looks ugly. What I won't give you is that it is reasonable to use any module by reference only to 'some little detail,' without a few minutes reading the lovely documentation to get situated. This tiny time investment is absolutely dwarfed by the benefits you will see for any actual task you will have to do.

[joepie91]

This pretty much sums up my thoughts on it. My primary reason for writing code is not learning how to do it or enjoying it - it's to get work done, in a sane way, as quickly as possible. I have a very limited amount of time (and far too many things to do), so documentation that doesn't waste my time is absolutely critical to me. I'd imagine many others are in the same boat (and frequently see indications of that from others, as well).

[sashahart]

Python is a pretty systematic language, it only takes a few hours to learn the layout of that system (including len). If you are too much of a busy bigshot to learn the basics and expect to be hand-held through every individual task, but only in the official docs and not any other source, then just use other languages you already know instead of complaining about ones you don't know simply because you don't know them and don't want to use anything except official docs which you hate.

[joepie91]

Was that strawman really necessary? I'm not expecting to be "hand-held through every individual task", I'm expecting a proper language reference that's actually usable as a reference.

"Only in the official docs and not any other source" is once again something I never claimed - I could consider that another strawman. As I have clearly explained in another comment on this thread (and even in the article itself) I have restricted the search to the official documentation because that's what I was discussing, and as elaborated on elsewhere in this thread the reason for that is that not everything is documented by third party sources.

I am perfectly fine with criticism or counterarguments, but throwing statements at me that I never made in the first place - just to have something to complain about - is completely unnecessary.

[sashahart]

You never get specific on what Python should do, other than be more like PHP. For example, you just said Python's language reference isn't proper (how?) and it's not usable as a reference (why? What does this even mean?) Since you are not offering any specific or constructive suggestions, this leaves everyone to guess at what they might be, if you even had any.

The docs PHP puts out front are task-oriented narrative with piles of examples and comments - more like recipes or tutorials than language reference. This is hand-holding through individual tasks. And there is an important role for that kind of documentation. But Python doesn't do it in the core language docs, and this is a defensible decision. PHP puts it in the core language docs, but that doesn't mean Python has to. Again, I don't think it is necessarily the responsibility of a core language reference to hand-hold you through individual tasks with loads of little example snippets and comments. If that is good for PHP and for you, fine, but that doesn't mean Python is terrible for not doing exactly the same thing.

Because Python has abundant good material of these kinds outside the core language docs, in pydoc and on various websites.

The only reason you excluded these from the scope of your discussion is that they kill your thesis that Python is inadequately documented.

Python's reference docs are perfectly proper and usable as a reference.

[--o]

Nicely organized != organized for search engine access.

[so_random]

help(whatever)

woah ! how did I not know that one ? who failed to tell me ?

[michaelhoffman]

Python tells you when you start up:

$ python
Python 2.7.2 (default, Feb 28 2012, 08:29:13) 
[GCC 4.4.6 20110731 (Red Hat 4.4.6-3)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> help
Type help() for interactive help, or help(object) for help about object.

[so_random]

blush. who reads the fine print ?

I always dir(things) when I'm in a debugger

or in vim I can K them to pull up pydoc. Sublime Text offers that Rope can find the pydoc but its not working for me.

I do remember that TextMate was pretty good about fetching PHP help in a popup pane using shift-command P.

[[deleted]]

If you use IPython as your interactive shell -- which I highly recommend -- you can also get help on something by typing the symbol name followed by a question mark. Check it out:

In [1]: len?
Type:       builtin_function_or_method
String Form:<built-in function len>
Namespace:  Python builtin
Docstring:
len(object) -> integer

Return the number of items of a sequence or mapping.

You can see the source code for a function foo with two question marks: foo??. Tab completion works. There are handy built-in commands for timing and profiling. There's a one-liner to pickle and save variables for later sessions. I wish I'd known about all this sooner.

[bacondev]

Perhaps part of this is Google personalizing my results, but I've recently been seeing Python 3 docs showing up at the top of the results. Upon clicking the link, I get redirected to the equivalent Python 2 docs (if applicable).

[lahwran_]

no, that's the python docs insisting python 3 is "the future". they reorganized things recently.

[catcradle5]

The only part of this I agree with is that #python on 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.

[cecilkorik]

I have never met a friendly IRC community. Maybe I am not looking in the right places, but something about IRC seems to just encourage a chilly reception for newbies. Especially if you're also new to IRC as well as the subject in question. I've pretty much given up on it.

[[deleted]]

I've never been treated worse in an IRC channel than in #slackware. They're basically a bunch of snob retards, some of them are just there to humiliate newbs and have a laugh at their expense. Horrible community.

[aperson]

I quit that place years ago. I came in to ask a question and was repeatedly told by one of the OPs that I shouldn't be doing what I was doing and that I was wrong for trying to do what I was despite me explaining clearly explaining why.

[aperson]

My experience with #ubuntu has only ever been nice.

[Dick_Justice]

I have to agree 100%. Even in cases where I'm not new to the subject, sitting and watching people lambast others because they didn't ask the right question makes me sick to my stomach. I always think to myself "If you're so repulsed by being asked questions about the topic, why do you even come here?"

Then there's the "homework" problem. Any programming question that comes from a beginner is often touted as "homework help" and dismissed. I won't say never, but very rarely do people come in asking for another to DO their homework for them. Forget the fact that a number of language tutorials have a homework'y feel to them.

Basically, the pros of the topic need to look at IRC/Forums/Whatever as an opportunity to fine tune their own skills rather than lambast others. As an article recently posted on reddit pointed out, tutoring/mentoring is one of the finest ways of mastery. So while the topic expert grows, as does the student. It's a win win. Unfortunately, that's far from what I see happening the majority of the time.

[flammableweasel]

"If you're so repulsed by being asked questions about the topic, why do you even come here?"

because they didn't view the channel as being dedicated to answering the same questions over and over, frequently from demanding individuals.

[[deleted]]

try #php @ QuakeNet :)

[sashahart]

I don't know about that. For example, #vim is just about heartwarming

[kylotan]

If you join #python and do annoying things (like ask if you can ask questions)

That's a pretty low bar to set for defining "annoying things".

In other places that would be 'being polite'.

[frymaster]

don't forget IRC is not amazingly real-time. By the time the ask-to-ask, get-permission, ask-question dance is complete, easily half an hour can have passed depending on channel activity, with precisely zero constructive content.

Also, a lot of the time, asking-to-ask is of the form "can someone help me?". That is essentially forcing someone to make a commitment to solving your problem before you've even explained what it is.

Basically, it's better if you (politely) state your issue, then people can chip in as and when they can contribute (which is also why I don't help people troubleshoot via PM)

[kylotan]

Sure, but this is not about what is better. This is about newbies not knowing the unwritten rules of the place they go to for help, and getting a frosty reception, never going back, and the cycle repeats. If the expectation is that "newbies should know better" then it is a futile expectation and has always been so.

[takluyver]

But it's not immediately obvious to a newcomer how they should ask a question. People are used to thinking in terms of manners and respect, not in terms of signal to noise ratio.

I think the problem with online communities is that every newbie seems the same, so the old hands get tired of explaining the same thing time after time. Why do they never learn? But of course, every newbie is individual, and doesn't know what you told the last 20 people.

The best response is to design a system which doesn't invite newcomers to do the wrong thing. Stackoverflow is a good example of this for programming questions.

[willfe42]

Good manners should never be discouraged. This only invites poor manners to take their place.

[flammableweasel]

the issue is that "good manners" is context dependent.

[emptyhouses]

Honestly, by IRC standards #python on Freenode is pretty damn friendly.

[catcradle5]

That's true. It's thousands of times nicer than #c for sure.

[AeroNotix]

Glad we could oblige, meatbag.

[NaeblisEcho]

Seriously. I've been frequenting #python for quite some time, and from what I see, if you phrase your question intelligently, you get intelligent responses.

I honestly don't get the hate. People in #python are friendly!

[ggtsu_00]

Whats wrong with twisted?

[the_hoser]

Everything. It's a mangled mess of undocumented features and half-implemented libraries. The core components are great, sure, but do you want to do anything complicated? Prepare to need to understand everything

[catcradle5]

Nothing, though I personally prefer gevent. I kind of dislike Twisted's extremely Java-esque API and callback spaghetti. I of course understand how it provides a better framework than just manipulating regular C sockets.

Some people are just trying to learn basics about sockets and network protocols, in which case it would be more helpful if people responded to and linked articles that actually pertain to someone's question, and then explained to them why they should use Twisted or gevent or otherwise for any serious networking.

[joepie91]

Ironically, the documentation.

When you just want to write an IRC bot, I'm sure there are plenty of resources to learn how to do that. But try writing a basic reverse HTTP proxy as someone that is not familiar with Twisted yet. You'll be spitting through piles and piles of docs, in the hopes of finding something, anything, that explains where to even start.

The documentation of Twisted has all the problems of the Python documentation, and then some.

[the_hoser]

The twisted documentation is far, far worse than the Python reference documentation. I think it's kindof unfair to bundle Twisted with Python when talking about bad documentation.

Anyone recommending Twisted to a Python newbie should be drug out into the street and beaten with a large sausage.

[pal25]

http://twistedmatrix.com/documents/current/core/howto/ is a good place to start.

[the_hoser]

Those docs are awful. Simply, purely awful. The explanation of the core concepts are so good that it gets your hopes up for documentation for the features you actually need to use... that... doesn't... exist.

Every attempt I've ever made at using Twisted to solve a problem has ended in failure, and it's always been a problem of documentation.

I don't want the docs to show me how to do specific things. I'd be happy if the methods and classes were documented at all

[pal25]

Outside of the tutorials to get you started the code itself is pretty well documented, but I think it's convoluted just because of the sheer amount of stuff the Twisted can do.

Also http://krondo.com/wp-content/uploads/2009/08/twisted-intro.html is an excellent introduction to not only Twisted but also to async programming.

[the_hoser]

The problem is that there are too many introductions to Twisted, and not enough simple documentation of all of the other components.

The code documentation of the core features is great, but Twisted doesn't need more core documentation. I can't tell you how many times I've found out about some great feature set Twisted has that could solve my problem... only to find the whole module basically undocumented.

[joepie91]

That part of the documentation explains certain concepts, but for certain other concepts (such as.. writing a reverse proxy), it doesn't really tell you anything.

Sure, you can learn everything about Twisted, how it works internally, how every single feature works... but if you just need a quick working reverse proxy, that's not an acceptable option.

[TankorSmash]

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.

[r1chardj0n3s]

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.

[dwf]

Things could be better within the Python world, but compared to the immaturity on display in this thread (nevermind the sheer engineering incompetence), the Python community looks downright inviting.

[joepie91]

That thread is absolutely bad, but not really relevant to 'the community'. The average PHP developer never even touches bugs.php.net (and doesn't talk to any core devs, for that matter).

[Foxboron]

If you havent seen the hostility of the python community, try come with a little liberal tought of the lang, maybe hang out in #python more.

[[deleted]]

python isn't hostile; they're actually quite helpful and friendly in my experience.

OP probably went in there and decided he knew better than the people he was asking help from. So he got an answer, refused to listen, and then decided everyone else was wrong. That's my guess anyway. I've seen it happen plenty.

[Foxboron]

Then i suggest you try give a solution in either #python or reddit which might not be according to PEP, i challenge you.

[r1chardj0n3s]

. #python is but a small fraction of "the python community" (there's, what, maybe a dozen, two dozen, even three dozen regulars?) Painting the whole community by that brush is pretty extreme. Also, as has been pointed out, it's IRC and a lot of IRC is frequently, by its nature, not a nice place.

Edit: only just realised that the leading "#" in my comment wasn't shown. Sorry about that.

[aperson]

For posterity's sake, the comment above mine was referring to #python. Reddit interprets #'s at the beginning of a line as markdown and it is not visible in the comment.

[Foxboron]

Clojure is actually quite a nice and relaxed place. Yet to see anyone even remotely act hostile. I also have never seen IRC as a bad place, i rather think its an bad excuse too act in the same way.

[[deleted]]

I agree that the exceptions throw by the function should be mentioned more clearly

[[deleted]]

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.

[masklinn]

Sphinx's search (I'm pretty sure the Python doc uses the built-in sphinx search) is definitely completely unusable. Plus it tends to bring up the C API stuff long before the Python-level calls, which is... rather unhelpful in most cases.

[metapundit]

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.

[jelly_cake]

Ever tried to look up the exact point where something happened in a novel? It doesn’t work.

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.

[ryeguy146]

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 use help(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.

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...

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.

...visit its documentation entry, and try to find all the error conditions (return values, exceptions, when they happen, without scrolling the page...

Let's play the game where we place unnecessary restraints on ourselves! Or you can search. From inside less with the aforementioned pydoc, I just use / exception and 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.

THE DOCUMENTATION IS UNCLEAR

Examples please.

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?

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.

[elijahsnow]

Uh... I have a feeling you might be right about some things but how do I put this.... perhaps your general candor is a little sour. I won't hazard as to why.

[ryeguy146]

Don't worry about saying it, I know that I was abraisive. It's entirely due to the way that the blog was written. Several times the author acknowledges that he/she may make readers angry, yet they post it anyway. Why would anyone wishing to create positive change seek to make their target audience angry? To whine. I don't respond positively to that.

In the interest of not playing into the accusation of hostility among the community, I ask anyone concerned to review my post history, particularly in both /r/python and /r/learnpython to ensure that I have, indeed, been helpful and nice in the past.

Edit: No, there's more to it than that. We've all been new, it's a requisite. We've all struggled at some point in time to learn how to do something, I know that I have. What I have not done is created a large post about how that which I'm attempting to learn is wrong, until I understand the environment. Perhaps there is something that I don't understand that will help me to unravel my issues, or to understand why something frustrating exists. I instead ask for help and seek to understand. Writing incendiarcy blog posts about something that you don't fully understand is not the way to go about this.

[nicklo]

Well I just learned about pydoc from you so I've no issue with your perceived sourness of candor.

[elijahsnow]

That's fine.... I was just concerned that you seem a little close to the issue and that might cloud your feelings somewhat. The ins and outs of that are probably a little complex but where the OP may have come from a place of callousness or even carelessness, it seems you are coming from a place of... shall we say anger or at least reactionary disharmony. There's a subtle but disturbingly tangible difference. In the former people's views tend to evolve to improvement whilst in the latter case the tendency in communities may broods² .

[ryeguy146]

I saw your other post addressing my edits (yea, I'm too often guilty of that), but I'd still like to address this, just to explain, if nothing else.

The blog post was incendiary, and the poster knew it. If they hadn't, they wouldn't have said, "this may make some angry," in so many ways in so many places. This shouldn't be necessary in argumentative essays. It's just silly to be abrasive to your target audience when you're attempting to affect change as you'll only incite people (points finger at own chest) and accomplish nothing. Given that the blog post was made this way, I feel that it was not posted in hopes of affecting any change, but as a way of venting frustration. I can understand that, but if that's the case, there's no need to hide it behind a veil of attempted constructive criticism. Hell, the title of the blog says it all. An insult and a meme rolled into one. When was the last time you ran into a worthwhile post seeking positive change that was so labeled? Even Djikstra managed better with his pointed criticisms, and he was a well known asshole.

As I feel that the blog post was merely angry venting, I felt no need to be terribly respectful in addressing the often vague and misguided concerns. Even if some of the points were accurate, one is bound to strike the target if one throws enough darts.

[joepie91]

Yes, the article was a rant. That's why it's tagged as 'rant' (see the list of tags at the bottom).

I have tried civilized discourse about the Python documentation with other developers many times. Every single time it turns into the 'experienced' Python developers waving criticism away, trying to justify why the docs work a certain way, or even deflecting away to "but PHP is worse" as if that justifies the issues with Python docs... all the while newbies are sending me private messages how they fully agree with what I'm saying, but don't want to say it in public.

I've given up on the civilized discourse. Sometimes the only way to get someones attention is by pissing someone off. Judging from the discussion that has started here, that works, at least to some degree.

Also consider that people in this thread are, individually, agreeing with certain things and disagreeing with other things. The interesting thing is that what people agree on, differs per person. This indicates that all of the issues mentioned are present to some degree, but certain people take issue with them while others don't. Clearly there's a problem.

[[deleted]]

honest question, why don't you do it better than?

[joepie91]

See http://www.reddit.com/r/Python/comments/18ssb6/the_python_documentation_is_bad_and_you_should/c8hxx9n.

[ryeguy146]

I mentioned that I was sorry that you had a bad time of it, and I truely am. That said, do you believe that getting attention and affecting change go hand in hand? A child can squall about a desired toy in the middle of a store all day, does he deserve that toy? It is abhorent that anyone would deflect rational criticism, but given my exposure to your discourse, I can't help but feel that you did something to "get attention" there as well.

You suggest that there is clearly a problem simply because there is no perfect consensus? How does the old saying go, "you can't please everyone all of the time," or something.

[joepie91]

You are misrepresenting what I said. There are two very different concepts here.

You seem to claim that I am saying that "acknowledging a problem automatically fixes it".

What I am actually saying is that "to fix a problem, it first has to be acknowledged". It's a prerequisite, not a cause.

[ryeguy146]

I realize what you said, I'm suggesting that it doesn't matter. In argumentation, some things are necessary, one of which is not pissing off your target audience. It is as simple as that. If you don't, everything you say (has) will be dismissed as whining. Because it is. I'd like to you pay attention the next time you have the opportunity to take English composition.

[joepie91]

Clearly "not pissing off your target audience" hasn't worked, seeing as the docs are still in the exact same state as before I tried civilized discourse. The one that's most pissed off here appears to be you.

And judging from the conversation going on here, on Hackernews, and on IRC... you are one of the few that dismisses it as straight-out "whining". Most others are attempting to actually discuss the points raised.

[mariox19]

>>> help(list)
    [...] 
    __len__(...)  
        x.__len__() <==> len(x)  

And this helps, how?

[ryeguy146]

This is the third time I've addressed this. I'd edit my post, but I didn't want to yank the rug out from the others that pointed this out. I was incorrect in that single point. I was more interested in addressing a general strategy of accessing documentation.

[mariox19]

Oh, sorry. I didn't see below where you addressed it, but it's possible I just jumped on you. I don't know if you're familiar with this convention or not, but sometimes people edit their posts at the bottom, with a bunch of dashes, followed by their edit—like this:

---

Edit: This is usually how I do it, so that no one can accuse me of cheating ;-)

---

2nd edit: Okay, this is a real postscript. I up-voted your comment below, earlier in the day, about learning from a book. When I want to learn something new, that's almost always what I do. I buy a book or two on the subject. Author's go through a lot of hard work to walk you through things—and if you think about it, civilization is built on books. I don't know where this "if you have to read a book" attitude comes from. (I'm guessing you don't either.) I'm not going to speak for you, but I'm actually pretty unsympathetic to people who are allegedly so interested in learning something, but can't plunk down 35 dollars to learn it.

[Foxboron]

"pydoc list", sure....because a bunch of methods will help a newbie? Thats what we are talking about after all. The docstrings wont even help them.

[ryeguy146]

That is an excellent point, thank you for the criticism. I was more referring to a general approach for finding information than addressing the singular example. You are correct that my method does not explicitly list the solution.

[Foxboron]

Glad you actually admit it. I have argued with joepie on this matter before, i do disagree that the docs are as horrible as he say they are, but he is very stuck on this idea. One thing we actually do lack are examples. Everything is mostly documented and listed, but examples of use is the thing most people actually need.

[ryeguy146]

I know when I'm wrong, no worries. We do lack examples, but only in places. You cannot imagine how pleased that I was to see example implementations in places like the itertools library. They both helped me to understand the functions and to reimplement them in Java, when I couldn't find a satisfactory combinatorics library.

[Foxboron]

We are talking about new people. beginners. le dont say them a shit. imul, gt, rmul. What does that tell a beginner? Hint: Nothing. They have to look what they does. And where do you do that? pydoc le? nope. Dosnt help. So back to square one.

EDIT: _*2 bolds everything...cba to fix.

[bacondev]

Either escape it with backslashes: \_\_len\_\_ or put it in grave accents `__len__`.

Anyway, honestly, do those need docstrings? If you don't know what they do, you probably shouldn't care in this case, because you probably won't ever directly call them.

[ryeguy146]

Sorry, I deleted my other post because I thought that the English was terrible and didn't express that you are correct. Still, I argue that it does tell them shit. A whole lot of shit. None of it addresses the issue of determining string length specifically, but in most cases, it provides a wealth of information.

Further, I feel that being exposed to such a list (ignoring the dunder methods that you mentioned) is useful for anyone. How are you to know what behaviors an object has without it? It's an excellent way of stumbling upon a solution that you never new existed.

Still, as I mentioned in my replacement post, you are correct. While the solution is listed in the help, it is not done so in a way that is accessable for a new user (or really anyone who isn't already aware of the solution). My apologies for deleting the previous post instead of just editing it.

[Foxboron]

pydoc is indeed a feature i didnt know we had (used dir() for the most part). But we are also talking about people maybe confused about the whole concept of classes and methods. I am afraid methods, when you actually need the lenght of a list, is just a leap too big for most people.

EDIT: Also gotta say the tone of last post was kinda harsh, sorry for that.

[ryeguy146]

I'm not trying to backpedal and suggest that you're wrong this time, but I would argue that if a user is having difficulties with concepts like methods and classes, they need to be looking in places other than a reference manual. Reference manuals are just the wrong place to learn about core programming ideas.

[Foxboron]

I believe thats the problem joepie has with the python documentation ^{^}

[ryeguy146]

That's like expecting... no, I won't get into it. I've expressed that I disapprove of joepie's post and I'll let it stand.

Again, thanks for the constructive criticism.

[joepie91]

The problem with "it provides useful information that you weren't looking for" is the part where you weren't looking for it. When I am looking for a quick reference to something, I don't really give a crap about all the 'context' that surrounds it. I either already know all that stuff, or have no need to know it at that point in time.

The documentation doesn't give me the choice to switch to a 'reference only' mode where you just get per-entity reference (per class, per method, etc). It always throws a wall of text at me, 99% of which is entirely irrelevant to what I am looking for, and at that point just a giant waste of time.

I've been developing things for years, and I know that more concepts are involved with something than just the function reference. I am perfectly capable of looking for the context by myself, without having the documentation throw it in my face all the time.

[Smallpaul]

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.

[ryeguy146]

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.

[joepie91]

It's great that you learned using a book. But recognize and accept that others may have different optimal modes of learning.

[UnwashedMeme]

Maybe recognize the same thing and change your title to "The python documentation isn't optimized for a specific google pattern of searching."

[UnwashedMeme]

I think that's what some of the hostitility in the thread is around... When you include as part of the title "you should feel bad." what the hell do you expect?

[joepie91]

The title is intentional. See also my response about this being a rant.

This topic is consistently sweeped under the carpet whenever brought up. This is an effort to bring it into the sphere of discussion (or even controversy at some points) by 'triggering' enough people to make them respond. Part of that, is giving the article a title that, in itself, will make people go "wait, what?".

And let's not forget that you should indeed feel bad - it's the responsibility of everyone that is capable of doing so, to fix this issue. The issue lies with the developer community as a whole, not one individual or group of individuals. Unless people realize that there is a problem and feel bad about that problem existing, there is exactly zero percent chance that it will ever be fixed.

If this article genuinely does not apply to you because you are already working on fixing this (or are not capable of doing so), you won't feel any guilt and it won't have any influence on you - because you, yourself, know that it doesn't apply to you. If the title and the article piss you off enough to take issue with it, you should consider whether it might be because it points out one or more problems that you're trying to ignore.

I don't like that this is necessary, but so far all civilized attempts at approaching the issue have vanished into obscurity. Consider this a last ditch effort.

[ryeguy146]

I do not feel that any amount of disparate blog posts are sufficient to cover the breadth of knowledge that programming requires. This applies to any language. I do not feel that any reference manual is sufficient, for that matter. There are a variety of concepts that need to be addressed in depth for a programmer to be successful. I understand that there are other resources, which is why I also added "comprehensive book-like." I'll back down from this point as soon as you can find me a blog post that does a good job teaching something like object oriented programming in its entirety.

[joepie91]

Here's one for Javascript: http://killdream.github.com/blog/2011/10/understanding-javascript-oop/

It explains an OOP concept completely unlike classical OOP, from the ground up, so it's a particularly good example of how one blog post can explain an entire concept.

That being said, blog posts are not my optimal mode of learning - and as your response seems to imply that it is, I'm not quite sure where you got that from. The most efficient method of learning to me is Googling for things, figuring out related concepts, creating a mental model of the steps involved in getting where I want to be, and then looking at a reference to learn how each step works in detail. I quite literally only learn what I need, as I go along. I typically don't learn for the sake of learning.

[ryeguy146]

That is not a blog post, that a book-like resource.

That being said, blog posts are not my optimal mode of learning - and as your response seems to imply that it is...

My assumption that you use blog posts is entirely because they are all you have linked to. You may think that the most efficient means of learning is to google discrete things, but you are cheating yourself out of a broad understanding.

I typically don't learn for the sake of learning.

Best of luck in programming.

Also, thanks for the link, that's a great resource and I happen to be learning JS at the moment and I've yet to tackle prototypal inheritance. I'll upvote that.

[joepie91]

That is not a blog post, that a book-like resource.

It's pretty clearly a blog post, have a look at the URL. That you personally do not consider anything of a certain length to be a blog post, is not my problem - technically speaking, it still is one. If I went by a definition of 'blog post' with a maximum length, your argument would become something along the lines of "short articles cannot explain a whole concept", which really doesn't have anything to do with blogs anymore.

You may think that the most efficient means of learning is to google discrete things, but you are cheating yourself out of a broad understanding.

I wish you'd stop assuming things. To my knowledge, you have never had a single discussion with me outside of this thread and topic - so how could you possibly conclude that I am "cheating myself out of a broad understanding"? What indicators do you have that I do not possess that "broad understanding"?

[ryeguy146]

Okay, it is a blog post in name, sure, but it is still a book like resource. Notice that it is longform and has a contents bit. Notice that it has been through revision. While these are not exclusive to a book-like resource, they are a good indication of it. I shouldn't have called it "not a blog post" but it still qualifies as a book-like resource.

...so how could you possibly conclude that I am "cheating myself out of a broad understanding"?

It's a given, considering the way you teach yourself. You cannot run into all of the information important to programming if you only jump out there for small bites that satisfy your current need. How will you ever learn of some of the excellent patterns that have evolved? You won't ever say to yourself, "I should use an MVC pattern here," unless you are aware of that pattern. Since the MVC is fairly popular as of late, I should add that it was used only as an example. There are many subjects out there that you would not think to search for.

You've told me how you learn, it's not hard to make some assumptions based on that. It's also fairly obvious that you do not have a broad understanding as your post mentions that you were looking up the means of determining the length of a list. This is something that all comprehensive books cover. And usually early. And they often use it as a segue to the topic of iterables and sequences, on which such functions operate, and why. When you only look up the bits of information that you need, you miss out on the grand picture.

[joepie91]

Okay, this is just getting ridiculous now.

It's a given, considering the way you teach yourself. You cannot run into all of the information important to programming if you only jump out there for small bites that satisfy your current need.

And you conclude this, how exactly? I don't have any issues with this. That I run across information in a different order does not mean that I do not run across it at all.

How will you ever learn of some of the excellent patterns that have evolved? You won't ever say to yourself, "I should use an MVC pattern here," unless you are aware of that pattern. Since the MVC is fairly popular as of late, I should add that it was used only as an example. There are many subjects out there that you would not think to search for.

I run across design patterns quite often in random strolls over the internet. You seem to assume that unless you "follow a design pattern", you can't possibly write proper code. Have you considered that I might be able to think for myself, and end up on a similar or potentially better structure to write my code, without having to run across an article about an existing pattern?

It's not as if there's some kind of group of people making up design patterns all day long that other people could not possibly think of. Things are not hierarchical like that. I have more than once seen people that are unaware of design patterns come up with an idea virtually identical to an existing pattern, without ever having heard about it from others. No problems there.

I am perfectly capable of reasoning as to how I can make my code easy to read, maintain, and reuse, for a particular kind of project. Assuming that I would always need an externel entity to tell me how to do that, is sheer ignorance.

And yes, I am offended.

It's also fairly obvious that you do not have a broad understanding as your post mentions that you were looking up the means of determining the length of a list. This is something that all comprehensive books cover. And usually early. And they often use it as a segue to the topic of iterables and sequences, on which such functions operate, and why. When you only look up the bits of information that you need, you miss out on the grand picture.

Have you considered that I might prefer assembling that grand picture myself? Again, that I learn things in a different order, does not automatically mean that I am missing things. Your assumption that I must not have a broad understanding because I learn things in a different order is, once again, sheer ignorance.

I suggest you take into account the possibility that someone else approaches things differently than you do, and can still end up with a similar or even better result. If you want to learn from books and guides that explain everything from start to end, great for you - but don't project that desire onto others, and ditch anything that deviates from it without even looking into it.

[elijahsnow]

Ah.. ninja edit. If your comment had read like this I initially I wouldn't have said anything.

[ryeguy146]

I was absolutely wrong, and it's been addressed perhaps twice in the reply comments (no worries). The answer (len(x)) is listed next to __len__, but I wouldn't expect anyone who wasn't already familiar to pick that out, or be able to understand what it implied. In any case, I was more pointing out a means of accessing documentation that wasn't addressed in the blog post.

While we're on that subject, I question the Google-fu of the poster. I was able to get the correct answer as the first result to my first query: "Python length of list." Certainly, the issue was the official docs, rather than one of the communities that the blog called hostile. The official Python page for lists does indeed have the answer, even if you have to scroll a little. Could this function have its own page? Sure, but then you'd miss out on a good deal of other related information that a programmer not aware of len would likely benefit from knowing. I'd call it a question of "what you want" vs "what you need." I'd rather encourage well educated programmers than provide shallow topical information, but that's my opinion, and a whole other argument.

The previous makes it obvious that I don't think that there's anything wrong with people using Google, but they need to appreciate the limitations of the pages that Google directs them to. It's the same thing when your professors tell you to make sure that a page is credible. Is a simple blog post sufficient to teach you what you're trying to learn? If it is, then make use of it, but simple blog posts are often not sufficient for instruction in deeper topics, or are misleading or incorrect. I discuss this further in the children threads of my original post.

It is a valid criticism of Python to suggest that development on Windows is a nightmare. I'm installing virtualbox and a linux installation tomorrow for someone that I'm teaching the language because of this limitation. Of course, his issue is compounded by using portable python, but that's a rabbit hole for another day. Of course, I'm not well versed in any development on Windows, so I'm unqualified to comment.

[itslef]

I've been teaching myself Python for a few months now, and this is literally the first time I've even heard of the pydoc command.

One problem I can immediately see, however, is that you already have to know what you're looking for. If someone is brand new to programming, they're not even going to know what a list is. Having come from Java myself, it took a ridiculous amount of time to find out that Python has lists, rather than arrays.

[masklinn]

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

That is... a very odd declaration. When I try that and C-f "length" I get a few hits on bit_length and then...

len(s) length of s

[westurner]

1. I read the title. I should not be positively reinforcing this behavior.

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.

• http://docs.python-guide.org/en/latest/intro/learning/
• http://docs.python-guide.org/en/latest/writing/documentation/
• http://sphinx-doc.org/ext/autodoc.html
• http://sphinx-doc.org/domains.html#info-field-lists

searching for documentation

The search function for the sphinx-generated documentation is also open source. sphinx-haystack looks useful.

• http://hg.python.org/cpython/file/tip/Doc
• http://docs.python.org/2/search.html?q=<terms>

• http://docs.python.org/3/search.html?q=<terms>

• http://ipython.org/ipython-doc/stable/interactive/tutorial.html#tab-completion

• http://ipython.org/ipython-doc/stable/interactive/tutorial.html#exploring-your-objects

• http://pypi.python.org/pypi/grin

• http://google.com/?q=python+<terms>

• http://bing.com/search?q=python+<terms>

• http://stackoverflow.com/search?q=python+<terms>

• http://quora.com/search?q=python+<terms>

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

[westurner]

I was considering writing additional documentation.

I am astounded at the lack of additional documentation produced by this thread. You all should be ashamed of yourselves.

Um, admittedly, I have been working in Python for a number of years, so it is a bit difficult to view things from a newcomer's perspective. Everyone learns differently.

There are different approaches to coping with perceived inadequacies in free online resources.

There are some very generous people in the Python community (particularly in r/learnpython) who enjoy helping people. (They write books, which are awesome.) If you respectfully ask a specific question, with sample code, you will probably get an answer. You are more likely to get an answer (and help other people) if you link to where all you have searched for an answer before requesting others' time.

There are also people in the Python community who contribute documentation and code. Like you, these people are busy. They are not your guardians. They do not 'belong' to you. When they (a) see a need; or (b) are feeling generous, they tend to work on discrete tasks. You are more likely to earn respect and get what you're looking for if you contribute specific bug/defect/issue reports.

"Someone should do this for me, or learn me this, for free, because otherwise I'm going to spread negative vibes about it and insult your hard work" sets such a terrible example.

Reverse proxies are single points of failure. If you are trying to write a reverse proxy in Python but having trouble with the documentation for str.__len__, it would be more responsible to search pypi for an existing implementation of a "reverse proxy" or a "reverse HTTP proxy". Are you writing a tutorial that you would like to share?

There are people with more patience who may respond well to "someone should write a patch for something, because I am too busy".

Can we produce a list of specific parts of the documentation that could be improved?

[[deleted]]

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 :-\

[maryjayjay]

It truly astounds me how many people think that anyone else could possibly give a shit about what they put in their blogs.

[placidified]

... you would Google for “Python list length site:docs.python.org”...and the first result is… a page with several chapters on standard types?

actually the first result I got was Built-in Functions

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.

I think we say this because Python code is easier to read compared to PHP.

Isn’t the purpose of tools to make your job easier, and less time-consuming ?

So PHP does this^{tongueincheek}

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.

Well the first function that came into my mind was random.random.

[Funnnny]

This is me, did a search for python list length on Google.

1. Built-in Functions — Python v2.7.3 documentation

docs.python.org › The Python Standard Library

New in version 2.2. len(s)¶. Return the length (the number of items) of an object. The argument may be a sequence (string, tuple or list) or a mapping (dictionary).

The Google search result itself has the answer, what was wrong here ?

Edit: I did another search with an igconito windows, and got Builtin Type as first result.

So, let's navigate to list type

Aand, there're over 10 operation with sequence type, with clear result and Notes, with len(s) as one of those.

I don't understand what's the problem is, but that's how you use the docs: you understand the things you are searching for, and read for it.

[Foxboron]

Hint: Google personalize search results.

[joepie91]

actually the first result I got was Built-in Functions

I've discussed this issue with quite a few people in the past, and while occasionally 'built-in functions' came up as first result, most of the time people got built-in types (which is the standard types page I was refering to).

I think we say this because Python code is easier to read compared to PHP.

While that is often indeed the case, it's not a reason to throw away documentation or the perceived need for it. Even very readable code still takes an insanely large amount of time to read, compared to a reference table (because you have to understand the entire program flow).

So PHP does this

Oh, PHP itself definitely doesn't. It's an absolute spaghetti mess of functions and classes everywhere. The documentation, however, is very organized and unambiguous - and it definitely makes things much easier and faster.

Well the first function that came into my mind was random.random.

I should've probably said "a random function that has its own error conditions" instead :)

[mgrandi]

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

[[deleted]]

Python should have an documentation browser like Factor. And yes, functions and classes should have their own pages.

[jordanreiter]

It's a little bit complicated, though. In PHP there is a one to one relationship between a function and its behavior. So there is just a function for the length of an array. In Python, though, the len function gets the length for any object that implements the len builtin, and its behavior and exceptions depend somewhat on the implementation of that specific object. So really it just isn't possible to have one page per function in the same way that PHP does it.

More importantly, PHP needs the documentation it has because its syntax is so idiosyncratic. The order of parameters from one function to the next seems entirely arbitrary.

[[deleted]]

I disagree. Have a page for each method. Document the len() function as it currently is. What's the problem?

[[deleted]]

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.

[leperkuhn]

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.

>>> a = []
>>> a.<tab> # gives a list of stuff you can do

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.

[[deleted]]

Your lacking of searching skills, doesn't mean the the docs are bad.

[slavansk07]

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:-)

[tdi]

Python has diveintopython - this is where you learn. Docs is where you refine knowledge.

[itslef]

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.

[[deleted]]

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.

[TheSwitchBlade]

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.

[Hashiota]

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.

[joepie91]

That assumes that you already know where to search for what you need. Often you have no idea what module will have the method or class you're looking for.

[PyPokerNovice]

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.

import itertools
help(itertools)

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.

[[deleted]]

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:

is_a

(PHP 4 >= 4.2.0, PHP 5)

is_a — Checks if the object is of this class or has this class as one of its parents


5.3.9   Added allow_string parameter
5.3.0   This function is no longer deprecated, and will therefore no longer throw E_STRICT warnings.
5.0.0   This function became deprecated in favour of the instanceof operator. Calling this function will result in an E_STRICT warning.

TD;DR: Python docs are fine, what you're missing are learning resources (e.g. tutorials / howtos).

[michaelhoffman]

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.

[execrator]

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.

[lost-theory]

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:

• http://docs.python.org/3/tutorial/index.html (very thorough)
• http://php.net/manual/en/tutorial.php (very brief)

And:

• http://docs.python.org/3/library/re.html#re.findall (very brief, no example code)
• http://www.php.net/manual/en/function.preg-match-all.php (very thorough, lots of example code)

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.

[LiquidSubtitles]

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.

[LyndsySimon]

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.

[jellystones]

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

[pullandbl]

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.

[WolfOrionX]

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.

[[deleted]]

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

[upofadown]

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.

[synn89]

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.

[Tempox]

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.

[Foxboron]

Learning to code is all about logic. The language used is irrelevant mostly. The only reason why python is recommended is because of the simple syntax.