5 ms·

The problem with python's website was never that it wasnt "Sexy" enough to attract newcomers. Its that the documentation was never as well written or well organ

The problem with python's website was never that it wasnt "Sexy" enough to attract newcomers. Its that the documentation was never as well written or well organized as other languages/libraries like ruby and jQuery.

petercooper 14y ago
I'm a Rubyist but I find that curious because the more common public complaint seems to be that Ruby's documentation isn't as good as Python's. (And its official site is rather tired, to say the least.)
disgruntledphd2 14y ago
I really liked Python's documentation. I read the tutorial and it got me up and running really quickly, and whenever I had a problem or needed details of the arguments it was an invaluable reference. Clearly, not everyone thought so. What did you not like about the docs?
- neutronicus 14y ago
  It's nice to learn from, but if you already know what you're doing and you just forgot the arguments to that one god damn method, it's pretty irritating to actually find the arguments to that one god damn method.
  - jodrellblank 14y ago
    >>> help(method) usually tells you.
simonw 14y ago
Really? I've always found Python's documentation (especially the official tutorial) to be excellent. What do you think could be improved about it?
- dgallagher 14y ago
  A navigable list of objects, functions, and methods would be really nice, something like this (preferably complete): http://api.rubyonrails.org http://api.rubyonrails.org Another suggestion would be to split tutorials/examples apart from object references. For example, take a peek at the Python Decimal module docs: http://docs.python.org/2/library/decimal.html#module-decimal http://docs.python.org/2/library/decimal.html#module-decimal All the information is there, but it isn't organized very well. There's a tutorial, overview of Decimal and its methods (with tutorials mixed within), and various "notes" sections. It's all mixed together, and confusing for a new user. Personally, I'm more of a fan of this type of structure: 1. API documentation. No how-to's. 2. "Guides" and How-To's API documentation is like a dictionary. Succinct, to the point, not littered with "Here's how you write a sentence with this word" examples. Guides/How-To's including examples, introductions to use an object, spell out caveats, etc... This should get wordy when needed. Both could have links to one another. For experienced coders, you'll mostly just use #1 (which fits great in a navigable list). For newbies, #2 will teach you how to do things. $0.02
  - zanny 14y ago
    Agrees on this. Sometimes you don't want the tutorial or book, you just want the reference guide of one liners saying what the thing is, at least for the proficient programmer. If I come back to Python from a few months on some C++ project and have to spend 15 minutes looking up how to use their JSON api because I have to dig 90% of the time to find callables the docs fail. The lack of a Javadoc / Qt ref / cppreference (I love that wiki) module / function list makes just searching for something you know exists and just need the method name a pain in the butt.
- testbro 14y ago
  The documentation is beautifully written and perfect for learning, but it doesn't support the quick-fire referencing I, and I presume the other detractors, have grown to expect. Contrast the first Google result for "python dictionary" [1] and "java hashmap" [2]. The Python result tells you about every data structure and does so in a story, the Java one gives you what you want and little more. [1] : http://docs.python.org/2/tutorial/datastructures.html http://docs.python.org/2/tutorial/datastructures.html [2] : http://docs.oracle.com/javase/6/docs/api/java/util/HashMap.html http://docs.oracle.com/javase/6/docs/api/java/util/HashMap.h...
obstacle1 14y ago
If Python's documentation is a "problem", then IMO the devs should continue doing problematic things. What in particular do you find lacking about the documentation? I've never heard this complaint before.
scott_s 14y ago
I find Python's online documentation to be fantastic. It's probably the best online documentation I use. I'm really curious what about it you find lacking.

petercooper 14y ago

I'm a Rubyist but I find that curious because the more common public complaint seems to be that Ruby's documentation isn't as good as Python's. (And its official site is rather tired, to say the least.)

disgruntledphd2 14y ago

I really liked Python's documentation. I read the tutorial and it got me up and running really quickly, and whenever I had a problem or needed details of the arguments it was an invaluable reference. Clearly, not everyone thought so. What did you not like about the docs?

neutronicus 14y ago
It's nice to learn from, but if you already know what you're doing and you just forgot the arguments to that one god damn method, it's pretty irritating to actually find the arguments to that one god damn method.
- jodrellblank 14y ago
  >>> help(method) usually tells you.

simonw 14y ago

Really? I've always found Python's documentation (especially the official tutorial) to be excellent. What do you think could be improved about it?

dgallagher 14y ago
A navigable list of objects, functions, and methods would be really nice, something like this (preferably complete): http://api.rubyonrails.org http://api.rubyonrails.org Another suggestion would be to split tutorials/examples apart from object references. For example, take a peek at the Python Decimal module docs: http://docs.python.org/2/library/decimal.html#module-decimal http://docs.python.org/2/library/decimal.html#module-decimal All the information is there, but it isn't organized very well. There's a tutorial, overview of Decimal and its methods (with tutorials mixed within), and various "notes" sections. It's all mixed together, and confusing for a new user. Personally, I'm more of a fan of this type of structure: 1. API documentation. No how-to's. 2. "Guides" and How-To's API documentation is like a dictionary. Succinct, to the point, not littered with "Here's how you write a sentence with this word" examples. Guides/How-To's including examples, introductions to use an object, spell out caveats, etc... This should get wordy when needed. Both could have links to one another. For experienced coders, you'll mostly just use #1 (which fits great in a navigable list). For newbies, #2 will teach you how to do things. $0.02
- zanny 14y ago
  Agrees on this. Sometimes you don't want the tutorial or book, you just want the reference guide of one liners saying what the thing is, at least for the proficient programmer. If I come back to Python from a few months on some C++ project and have to spend 15 minutes looking up how to use their JSON api because I have to dig 90% of the time to find callables the docs fail. The lack of a Javadoc / Qt ref / cppreference (I love that wiki) module / function list makes just searching for something you know exists and just need the method name a pain in the butt.
testbro 14y ago
The documentation is beautifully written and perfect for learning, but it doesn't support the quick-fire referencing I, and I presume the other detractors, have grown to expect. Contrast the first Google result for "python dictionary" [1] and "java hashmap" [2]. The Python result tells you about every data structure and does so in a story, the Java one gives you what you want and little more. [1] : http://docs.python.org/2/tutorial/datastructures.html http://docs.python.org/2/tutorial/datastructures.html [2] : http://docs.oracle.com/javase/6/docs/api/java/util/HashMap.html http://docs.oracle.com/javase/6/docs/api/java/util/HashMap.h...

obstacle1 14y ago

If Python's documentation is a "problem", then IMO the devs should continue doing problematic things. What in particular do you find lacking about the documentation? I've never heard this complaint before.

scott_s 14y ago

I find Python's online documentation to be fantastic. It's probably the best online documentation I use. I'm really curious what about it you find lacking.