Hacker News Reader

Comment by f1refly | Hacker News Reader

> Actually, in the doc you described as "obviously the correct hit", all I see is

>> str.endswith(suffix[, start[, end]])

>> Return True if the string ends with the specified suffix, otherwise return False. suffix can also be a tuple of suffixes to look for. With optional start, test beginning at that position. With optional end, stop comparing at that position.

> Meanwhile, the first hit in Google for me is Programiz, which has actual real examples without any additional clicking around or trying to understand how the information is structured.

I'm sorry, but what examples could you possibly want that the official documentation doesn't make clear? It's written as concisely as can be, describing the possible inputs and the expected outputs of the particular function, no? I don't see how sifting through tens of lines explaining what the docs say in two short sentences is preferable.

View on HN

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.

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.

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

Any? Any example would do.

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.

Reply on news.ycombinator.com