4 ms·

I think the Python docs are fine. I use them all the time. (The re docs in particular.) It's not beginner-focused, but it'd suck if the current docs were repla

I think the Python docs are fine. I use them all the time. (The re docs in particular.) It's not beginner-focused, but it'd suck if the current docs were replaced with docs for beginners. The re page has over 7,000 words. I need those 7k words. They help me get things done. Perhaps a solution might be something like a https://simple.docs.python.org https://simple.docs.python.org type site: A simplified version, parallel to the existing documentation, consisting mostly of examples. I'd use it.

mrweasel 10y ago
The issue with the Python docs is that you have to ACTUALLY READ IT. Some language have documentation that you can just sort of skim and pick out the bits you think you need. The Python documentation, and the Django documentation have additional information in the text. Describing how a module or function works, what you can expect and how you should use it. Important information is often "hidden" in the text and if you're the sort of person that doesn't actually read the documentation you're going to get it wrong. The Python docs are absolutely fine, because actually tries to teach you how stuff works and why it is the way it is.
- tgwallace 10y ago
  I think the docs are often too verbose. Many pages start with a long winded intro that misses the main point. Some pages never get to the point. Docstrings are sometimes several pages long. Example of not getting to the point: Extending/Embedding. There is no fundamental difference. In both cases you're just calling a bunch of functions from libpython.a.
- collyw 10y ago
  I like Django docs. They are lacking information in some places but generally about right. Python's docs are the opposite, they have too much information. I just want to remember the calls for using a reqex with capturing groups, and its about 5 pages of text into the document.
- falcolas 10y ago
  > if you're the sort of person that doesn't actually read the documentation Is this a problem with the documentation, or the reader? Perhaps it's just me, but I can (and do) skim the Python library documentation regularly. Due to the high level nature of Python, any given bit of code is doing a lot of work under the covers. I'd rather that complexity is properly documented than glazed over in the official language documentation.
noufalibrahim 10y ago
This gap is very nicely filled by the Python Module of the Week series https://pymotw.com/3/ https://pymotw.com/3/ which focuses on examples rather than exhaustive docs. I believe the blog is coming out as a book called "Python standard library by example".

mrweasel 10y ago

The issue with the Python docs is that you have to ACTUALLY READ IT. Some language have documentation that you can just sort of skim and pick out the bits you think you need. The Python documentation, and the Django documentation have additional information in the text. Describing how a module or function works, what you can expect and how you should use it. Important information is often "hidden" in the text and if you're the sort of person that doesn't actually read the documentation you're going to get it wrong. The Python docs are absolutely fine, because actually tries to teach you how stuff works and why it is the way it is.

tgwallace 10y ago
I think the docs are often too verbose. Many pages start with a long winded intro that misses the main point. Some pages never get to the point. Docstrings are sometimes several pages long. Example of not getting to the point: Extending/Embedding. There is no fundamental difference. In both cases you're just calling a bunch of functions from libpython.a.
collyw 10y ago
I like Django docs. They are lacking information in some places but generally about right. Python's docs are the opposite, they have too much information. I just want to remember the calls for using a reqex with capturing groups, and its about 5 pages of text into the document.
falcolas 10y ago
> if you're the sort of person that doesn't actually read the documentation Is this a problem with the documentation, or the reader? Perhaps it's just me, but I can (and do) skim the Python library documentation regularly. Due to the high level nature of Python, any given bit of code is doing a lot of work under the covers. I'd rather that complexity is properly documented than glazed over in the official language documentation.

noufalibrahim 10y ago

This gap is very nicely filled by the Python Module of the Week series https://pymotw.com/3/ https://pymotw.com/3/ which focuses on examples rather than exhaustive docs. I believe the blog is coming out as a book called "Python standard library by example".