3 ms·
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 t
by 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 agoI 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 agoI 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.