I don't know if you're trolling or not.

When you get good at it, it is much easier to skim through 10 lines of fluff to find the answer (that is usually visually distinguished in a code block) then it is to parse through 4 really dense, terminology filled sentences.

If I need to know exactly how all the options work, sure the docs are the place to go, but 90% of the time I just need a quick example to go off of.

I'm not trolling. From my perspective mastering a language includes mastering its included library (for things like python where its standard library is indeed what everyone is using). Thus, it is always preferable to read the complete documentation for some functionality and pick up every detail along the way instead of having an idea in your head how to do the thing you want and picking only the exact use case you wanted from an example.

> If I need to know exactly how all the options work, sure the docs are the place to go, but 90% of the time I just need a quick example to go off of.

You will almost never get to the point where you'd need to know "exactly how all the options work" because if your routine is "search example, copy example, continue", you won't even know what options exist and that there is a way you could do things different (maybe more efficient? simpler?).

Php docs get this right in a way that works for many more people than Python does.

Agreed. For all of the hate PHP gets, the state of their respective docs was a big pain point for me in trying to learn Python after years of writing PHP.

However, the PHP docs, especially for older, less-used functions, are riddled with subtle errors and inconsistencies related to the typing of arguments and handling of edge cases. But the way they're structured is fine! I particularly enjoy how you can type php.net/sprintf and land directly on the doc page you're looking for.

> I'm sorry, but what examples could you possibly want […]?

Any? Any example would do.

Official python docs are awful. Same with MSDN. Docs should be more than just the auto-generated pydocs which just parrot the function signature—which I can easily infer because I can, you know, read.

For any sufficiently complex function that requires me to actually look up the docs, I want example usage. Not all arguments are obvious. Not all return types are obvious. This is especially bad for overloaded functions. Worse is when docs requires a circular graph traversal of clicking endless links to more documentation.

Needless to say, I prefer content farms and blogs to the official docs.

Humans are much better at inferring rules from examples than at deducing an example from a concisely stated rule. The official python docs are the latter.