65 ms·

Python is a great language, despite its quirks. Imagine how popular Python would be if it had decent basic documentation and a single active version? The confus

Python is a great language, despite its quirks. Imagine how popular Python would be if it had decent basic documentation and a single active version? The confusion caused by Python 3 caused at least a decade of slow adoption and the docs, well, that's pretty much a lost cause. (Compare https://docs.python.org/3/library/os.path.html https://docs.python.org/3/library/os.path.html to https://nodejs.org/api/path.html https://nodejs.org/api/path.html - the latter has a nice summary at the beginning, an index of methods at the top of the page listing everything below, method inputs and return values are noted for each method clearly, concise non-interactive terminal examples that you can copy/paste for each method is given, the exact version the method was added, a collapsed history of changes and any error types thrown. My only assumption is that the Python maintainers must have a side deal with O'Reilly to keep the docs in the worst format ever as a source of continued revenue for both.)

mjw1007 9y ago
I'd say that, over the last twenty years, Python's docs have gone from excellent to good to middling to excellent to good to middling (dropping as the language expanded and the generally expected standard went up, and improving when they did one major revamp). So I agree that another revamp would be good now, but I historically the docs have been a plus as much as they've been a minus, relative to Python's alternatives.
- dom0 9y ago
  Much plain reference data is missing from the docs (like return types). Its neat to describe a function, but if you don't hand out the API, then the docs are not all that useful.
antod 9y ago
I'm doing mostly Ruby now and I miss the Python docs.
apple4ever 9y ago
Python's documentation is terrible! I do like Python (only been using it for about a year), but the docs make it so hard to figure out how to do something.

mjw1007 9y ago

I'd say that, over the last twenty years, Python's docs have gone from excellent to good to middling to excellent to good to middling (dropping as the language expanded and the generally expected standard went up, and improving when they did one major revamp). So I agree that another revamp would be good now, but I historically the docs have been a plus as much as they've been a minus, relative to Python's alternatives.

dom0 9y ago
Much plain reference data is missing from the docs (like return types). Its neat to describe a function, but if you don't hand out the API, then the docs are not all that useful.

antod 9y ago

I'm doing mostly Ruby now and I miss the Python docs.

apple4ever 9y ago

Python's documentation is terrible! I do like Python (only been using it for about a year), but the docs make it so hard to figure out how to do something.