Hacker News Reader

Comment by reaperman | Hacker News Reader

I love docs.python.org -- it feels close to perfect for me. Other programming language references like Java are quite difficult for me to use. Cplusplus.com and cppreference.com also feel very usable for me, but not quite as good as docs.python.org

View on HN

This is obviously a personal preference thing, but I just want to mention a counterexample that I find the Python docs incredibly frustrating, and the worst of any language I've used. Going by the 4docs methodology, I am usually looking for reference docs, and Python seems to only have tutorials, even when they call them references.

The most common reasons I check the docs are because I want to know all the functions available for an object, or what type of parameters a function expects, or what a function returns. None of these are straightforward in the Python docs, and you often have to read several paragraphs of text that may or may not have the answer.

Here's one example: https://docs.python.org/3/library/urllib.request.html#module...

What type is cafile supposed to be? You have to ctrl-f or read a bunch to find out that it doesn't even say. I guess you're supposed to assume it's a string from the context (or is it some kind of File object?). If you work primarily in Python and you're familiar with the conventions this might be obvious, but if you're not a frequent Python user and don't immediately remember if there's a special Path type or not, this is annoying.

What does that function return? There are three paragraphs describing the potential return types in the middle of a very long docstring, they aren't highlighted in any way even though this is pretty fundamental information, and they aren't comprehensive. I might need to click a couple links to figure out what exactly this function is giving me.

Here's another example: https://docs.python.org/3/library/datetime.html#datetime.dat...

Is timestamp a string or a number? Again you're just supposed to already know the Python conventions, or go do trial-and-error in the REPL.

These issues are pervasive for me on docs.python.org - it always feels way too verbose while lacking basic details. Every time I visit a page I wish there were a simple quick reference table at the top listing all the functions and their types before it dives into the minutiae.

Hate to be that guy, but your first example is not that frustrating to me. I liked the 2 sentences per parameter, and the line breaks between them. I don't like the general python idiom of "these parameters are for someone else" where they just pass you off to the ssl module documentation. I understand why they do that, they probably just pass them over in code. The Rust community is better here, they take responsibility for every parameter and type input, both for documentation and for backwards compatibility.

I think most of your beefs are, "what are the types of things", but Python wasn't very type savvy until pretty recently, so stuff was generally very implied. If you wanted type info you had to explicitly notate it in docs, which was kind of laborious and not easy to make perfectly accurate, so most people didn't do it (also it works against duck typing, like must this be an `int` or just something that supports `__add__`?). It's maybe also worth saying that if you click in the `time.time()` link in the 1st sentence of your 2nd example you'll pretty quickly see many indications that the return type is a float.

I'm (maybe this goes without saying) a big fan of the Python docs. They make simple things easy by covering the 80% use cases really well, and for the rest they link source code up at the top. Django does this too which I really appreciate. I think you generally learn to use the affordances of the internet and browsers (cafile site:docs.python.org, ctrl+f) with all websites like, I mostly don't want websites reimplementing that stuff--usually worse--for me.

I would contrast it with the Python gRPC docs [0] which are a lot more type-savvy but don't really very much context about what the methods and such do. Like I've read [1] about 4 times and I don't understand it any better than after the 1st read.

IDK all I'm saying is there's more to it than just type information. Communicating technical information to people is really involved.

Those seem like valid complaints to me. Thank you for sharing, it opens my view to other people's needs.

Reply on news.ycombinator.com