Hacker News Reader

Comment by hackinthebochs | Hacker News Reader

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.

View on HN

This came up on HN a couple weeks ago, I have been quite impressed:

http://devdocs.io/python

CTRL + f / Command + f => "module.function" and you are done.

He already searched, on google. He shouldn't have to search twice for the same thing.

google is not python 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:

1. Google "Python os.unlink".

2. First link is https://docs.python.org/2/library/os.html which starts at the very top of the documentation for the os module.

3. CTRL + f/Command + f for "os.unlink".

4. The first result on the page is right around https://docs.python.org/2/library/os.html#os.mkfifo.

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 seems like google's fault. Example search for setUpClass python:

https://www.google.com/search?q=python+unittest&ie=utf-8&oe=...

First link is correct, and so is the snippet in the search result. When you click on the link, it should have taken you to:

https://docs.python.org/2/library/unittest.html#setupclass-a...

which is the anchor / title closest to the snippet found, as opposed to the main page:

https://docs.python.org/2/library/unittest.html

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.

Reply on news.ycombinator.com