I'll tell you whats wrong with python docs. When I google for a function and I see from the search results that the page has exactly what I'm looking for, when I click on the link I am instead presented with a long page of irrelevant information that I then have to filter through. It's so bad that I actively avoid the official docs.
I'd be fine with that if it ended there, but usually the word I'm searching for is in the document in a hundred different places (I forgot to mention that I usually don't know the exact method/object name). It almost always turns into a frustrating process of scanning the page manually.
Well, if you don't know the exact method or object name, how do you expect Google to guess what you need? Let's take a simple example of searching for Python's os.unlink method:
5. Click on os.unlink words because it's an actual link.
That last bit is very important. Every bit of documentation typically has a link from any module/object/method to its canonical documentation location. Contrast this with Django REST Framework, which does not do this and their docs are basically unusable because of this.
I agree that this could be shortened somehow to Google "Python os.unlink" and the first result being https://docs.python.org/2/library/os.html#os.unlink but it's such a minor flaw compared to everything else I've ever seen in terms of searching for docs that I am willing to live with it.
Contrast this with PHP's docs. Here, it's great: just go to http://php.net/YOUR-FUNCTION and you'll get the docs. For example: http://php.net/implode. What I don't like about these docs is that they often lie to your face. As in, they are just plain inaccurate and the way you find this out is by having your production code blow up. That right there is actual bad documentation.
>Well, if you don't know the exact method or object name, how do you expect Google to guess what you need?
I dunno, but google manages to do it pretty well. Like for your example, I might search for "python delete file" since I don't remember unlink. Ignoring the stackoverflow results, the first doc result is the right one, but I'll have a hell of a time finding it on that page. Looking at the next result tutorialspoint, the page itself is exactly what I was looking for. Tutorialspoint is quite excellent in this regard and I've started going there first.
That's a good example. I'd argue that it's very quick to find what you are looking for here. The first result is a Stack Overflow page where the first question links directly to what you are looking for. I definitely can agree that the docs can be better, but at the same time I cannot honestly call them bad. Bad docs are docs that either lie or docs that are not there, and possibly docs that are so ugly they hurt your eyes. Python's docs are anything but.
This is a bit OT, but I started finding Google search results a lot less useful after they shortened the amount of context they quoted.
I think that even in an example like the one you cite, this has some relevance. When the quoted context was larger, it seemed to me easier to find it -- scanning visually -- within the target page.
Of course, there is also the matter that with Google's loosened matching and/or increased page dynamism, results these days pertain less often to what I'm interested in. Not all that infrequently, I'll click through on a promising result, to find little or no hint of the context that Google quoted.
TL;DR: More anecdotal grumbling about the decreasing usefulness of Google search results.
is probably the first thing that pops up when you search of python and tutorial, yet it reads like it is adressed at people that are looking for a way to augment their unix shell. This is not very helpful to most people. Thankfully, there are many alternatives, however it is bad that this is the first thing that pops up.
I am confused by the why is "X so slow" argument. Conceptually and practically, Python might be slower than native C code, but the tradeof lies in the relationship between runtime and "design"-time. It is a little slower, but it is faster to learn, read and write. Demands for "more performance" should be driven by actual numbers: How many people should your webservice serve in a second, minute? So far python has been fast enough for anything I wanted to do. For everything else there is numpy/scipy - fortran for the win!
I am not entirely convinced that there is actually an inherent tension between runtime performance and being fast to learn, read and write. So it might just be that Python is simply slow, and although it has a lot of nice features, the slowness doesn't really have much of an upside.
There is no such tension inherently, yet I have seen a lot of violations of good practices in the name of "more performance". C# might be slower than C++, yes, but the question is: is it fast enough for what I would like to do? The fact that it is garbage collected and doesn't require pointer syntax makes it nicer to use, yet it runs slower. I have made similar experiences with databases, normalization is often discarded due to performance concerns (woohoo, too manz joins). It is true, making a join is slower than not making it, but the performance is gained by having less redundancy checks (I know, I am oversimplifying this). I am just very tired of seeing performance as an infinite target for optimization at the cost of maintainabilty, readability and so on. Exaggeratingly I could state: If you want it REALLY fast, write it in assembly.
Do you see what I mean?
As a follow up on my opinion, here is another item that was recently on hn. Tj Hollowaychuck is leaving node for go, mentioning this discrepancy (runtime focus vs working with it time focus) as a reason
https://news.ycombinator.com/item?id=7987146
Guess: a lot of developers conflate Python documentation with documentation for various Python libraries as found on PyPI. Documentation for these libraries varies from great to "I'll just read the source."
I've actually found myself doing quite a bit of code reading for Django. As much as the team tries, there is quite a bit of undocumented magic that can really trip you up if you are not doing exactly the right things. For example, don't create a source-tree/project/__init__.py file (sibling to your settings.py) that does any type of imports.
I'm going to guess that any dev worthy of the name can discern between a library and core python. I'll allow that I may hold python devs to a standard higher than is realistic (I'm new to using python in my daily work, and not well-versed in how the python community rolls.)
As noted elsewhere, there can be a lot of Ctrl/Command-f'ing to find what you want. That, and sometimes I just want an example of what I have to think is the most common case for a function. Instead I often get examples of esoteric cases that I'll likely never do. I mean, it's nice that those capabilities are there and that they're documented, but I just want to (made-up example) search for a simple ASCII substring, not a UTF-8 substring in a Unicode string using a regex all fourteen optional parameters.
That said, I wouldn't go so far as to say that the docs are bad, but they could certainly be better.
Agreed on the whole, but if we can agree that for ever good developer there are 10x beginners, we can infer that it's the 10x beginners' searches that influence the Google autocomplete.
That's something I love about JavaScript. Most libraries have great documentation, and the source is usually easy to understand. With C#, I feel the opposite is the case. Documentation either doesn't exist or is very basic, reading the source is quite hard because its common to put code in as much files as possible.
Really? I think a lot of people find the opposite to be true about Javascript, in terms of source. Javascript allows for some fun magic, but that pretty quickly cuts into readability/debugability. Look at Bluebird -- works great, but not just a "I'll jump right in here and understand it" sort of module.
You're definitely right about the C# docs, though. I always feel totally lost looking through those, especially since I'm not much of a C# dev to begin with.
