3 ms·

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 usu

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]

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]