Hacker News Reader

Comment by tiagoma | Hacker News Reader

Qt docs, python docs, cppreference, code synthesis odb

Python? I find the documentation to be confusing and difficult to search. Many of the arguments to standard functions are not explicitly documented nor do they have obvious enough names for me to guess what they mean. As I was learning Python over the past few years, I inevitably turned to blog posts and Stack Overflow for clearer examples and more explicit descriptions of optional parameters.

I'd be curious to know what you like about the Python documentation because my experience has probably been different than yours.

Absolutely. I had a hard time going through Python documentation during the early days.

I feel similarly about Python. I never really had to interact with it beyond using it as a calculator on the command line until a project I was a part of earlier in the year had a utility Python script introduced and I needed to hack on it to make desired changes. Then, more recently, I started using BeautifulSoup[0] for personal scraping. Of course it feels more trivial now (and now I wish I documented my frustrations so I could be more specific and perhaps help out other Python learners in the future), but it does take a while to adjust to Pythonic code where everyone is using cultural conventions like _foo and __foo and you wonder what the hell __foo__ is[1].

More on-topic, searching is a major weakness of Python's docs. What's that? Python just got multi-line strings allowing embedded expressions? They're called f-strings? Let me go read about them[2]. I can't link it, but even using Startpage the immediate results are a post from RealPython and PEP498 and while both are great, they aren't terse enough to be frequently referenced. If you search for "formatted string literal"[3] in the docs it takes 10 results before you reach something explicitly talking about them. And then you need to follow the links a couple times to reach https://docs.python.org/3/reference/lexical_analysis.html#f-... (notice it is anchored as "f-strings" which was the first term we searched for).

While the Python docs, when I've found them, have been adequate for me so far -- although I still check up on how others do the things I want to do -- I'm partial to docs such as MDN that cover parameters and return value in one take for reference with more in-depth information as you scroll down, if needed[4].

[0]: https://www.crummy.com/software/BeautifulSoup/

[1]: Here's a start for reading. https://stackoverflow.com/questions/8689964/why-do-some-func...

[2]: https://docs.python.org/3/search.html?q=f-string

[3]: https://docs.python.org/3/search.html?q=formatted+string+lit...

[4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

Reply on news.ycombinator.com