Python docs disappointing

[Chris Angelico]

On Thu, Dec 4, 2014 at 9:27 PM, Albert van der Horst
<albert at spenarnc.xs4all.nl> wrote:
> That doesn't help. I'm a very experienced programmer and work in
> routinely a dozen languages. Sometimes I do python. I want to do
> numeric work. I remember the name numpy. It is important, everybody
> knows it, it is all over the place. So I want to find its docs,
> or some lead, whatever. I go to the official Python site,
> http://docs.python.org and type in numpy in the search machine.
>
> It is embarassing, try it!
>
> Plain google is far superior in finding information.

Part of getting to know a language is learning what the best way to
find information about it is. When I want Pike documentation, I always
go direct to the docs (usually to my own build of them, to be sure
it'll match my locally-compiled Pike, so that's
http://sikorsky:8080/modref/index.html), but for most other languages,
it's better to use a web search. Sometimes your best result isn't the
official docs at all, but a StackOverflow post. Or maybe it's part of
the official docs, but not the module reference page (if you want to
know about argparse basics, the python.org howto is probably better
than the main page). As an added bonus, you don't need to "go here,
type this into search" - you just type what you want into your
browser's search box, or at very worst, pull up a link you probably
use a hundred times a day and will be cached.

> And you tell me that writing yet another tutorial would improve that?
> No, there is just one way. The powers that be should look critically
> at their website, and test it with a beginners hat on.

"The powers that be" implies that there's somebody else who is
obligated to provide a service to you. I don't think that's really the
case. That said, though, your other points are quite right; another
tutorial won't help, and improving search will help.

ChrisA