3 ms·

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'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.

IgorPartola 12y ago
CTRL + f / Command + f => "module.function" and you are done.
- flebron 12y ago
  He already searched, on google. He shouldn't have to search twice for the same thing.
  - rambojohnson 12y ago
    google is not python docs.
- hackinthebochs 12y ago
  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.
  - IgorPartola 12y ago
    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 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 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 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 http://php.net/YOUR-FUNCTION and you'll get the docs. For example: http://php.net/implode 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.
    - hackinthebochs 12y ago
      >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.
      - IgorPartola 12y ago
        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.
    - deleted 12y ago
      [deleted]
ejp 12y ago
This came up on HN a couple weeks ago, I have been quite impressed: http://devdocs.io/python http://devdocs.io/python
makmanalp 12y ago
This seems like google's fault. Example search for setUpClass python: https://www.google.com/search?q=python+unittest&ie=utf-8&oe=utf-8&aq=t&rls=org.mozilla:en-US:official&client=firefox-a&channel=fflb#channel=fflb&q=python+setUpClass&rls=org.mozilla:en-US:official 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-and-teardownclass 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 https://docs.python.org/2/library/unittest.html
- pasbesoin 12y ago
  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.

IgorPartola 12y ago

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

flebron 12y ago
He already searched, on google. He shouldn't have to search twice for the same thing.
- rambojohnson 12y ago
  google is not python docs.
hackinthebochs 12y ago
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.
- IgorPartola 12y ago
  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 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 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 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 http://php.net/YOUR-FUNCTION and you'll get the docs. For example: http://php.net/implode 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.
  - hackinthebochs 12y ago
    >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.
    - IgorPartola 12y ago
      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.
  - deleted 12y ago
    [deleted]

ejp 12y ago

This came up on HN a couple weeks ago, I have been quite impressed: http://devdocs.io/python http://devdocs.io/python

makmanalp 12y ago

This seems like google's fault. Example search for setUpClass python: https://www.google.com/search?q=python+unittest&ie=utf-8&oe=utf-8&aq=t&rls=org.mozilla:en-US:official&client=firefox-a&channel=fflb#channel=fflb&q=python+setUpClass&rls=org.mozilla:en-US:official 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-and-teardownclass 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 https://docs.python.org/2/library/unittest.html

pasbesoin 12y ago
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.