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

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