Hacker News Reader

Comment by inglor | Hacker News Reader

I think a big part of it is how much canonical documentation and resources has improved in JavaScript vs. how much people are struggling with it in Python (as someone who does more Python than JS but does both).

Python libraries tend to have less documentation and their documentation tends to be less live whereas JavaScript has been more stable lately (something I didn't think I'd ever write).

Funnily enough the last time I really struggled with a JavaScript library's docs it was Tensorflow.js (a Python port).

Also, I'd love to see a comparison that checks "all" JavaScripts (+TypeScript).

View on HN

Another thing I've noticed is that the Python community in StackOverflow is very nice and considerate most of the time compared to the JavaScript crowd. (Being a part of both).

If anyone is interested in engaging by the way: https://sopython.com/

This seems true of the Python community in general. I've yet to meet anyone that's not nice and really supportive (there are bound to be some, but I've not knowingly interacted with them).

I think it's a great measure of a programming language's ecosystem when taking part in the community is such a pleasure.

From the beginning the language has taken great pains to be readable and comprehensible. It makes sense that would breed a community that values empathy.

That's a good point! Though I think a big part of it is that the web stack changes a lot more often which breeds a lot of fear that kills empathy.

I've met some of the nicest people I know in the JavaScript open source community and some of the most empathic though.

I don't recommend heading over to #python on Freenode then, if you want to maintain that belief! They're a bunch of purists, it's hard to squeeze a practical response from them a lot of the time.

That's because programming in python is fun so we aren't as stressed! I'm only kidding but there might be some truth in this worth exploring.

There is no such things as the js doc. Only a huge number of 3rd party websites such as w3school, mdn, so, etc.

Also python has readthedoc for non stdlib doc, for js it's very heterogenuous.

All in all, I think the doc situation could be much improved, but not compared to JS.

> Funnily enough the last time I really struggled with a JavaScript library's docs it was Tensorflow.js (a Python port).

I think it's interesting how you mention that you struggled with the docs of Tensorflow.js and attribute that to it being a Python port, rather than it being the absolute cutting edge of machine learning. Are other state-of-the-art , pure JS ML (or similar level of complexity and novelty) libraries better documented?

That's a fair point. In this particular case the documentation was significantly worse than most new JavaScript libraries I'm used to and pretty similar to most Python libraries I'm used to.

Sometimes parameters were missing, what values you can pass in were missing and there was a general lack of documentation on how to do things (sans a few tutorials).

I can name a bunch of examples. Here is a very simple one: what values can I pass as a loss function to LayersModel#compile? (I had to dig through the code to figure it out)

( https://js.tensorflow.org/api/latest/#tf.LayersModel.compile ) There is just consensus in JavaScript that things that don't get well documented don't get adoption.

Hmm, this has not been my experience with Python libraries (I can't speak for JS ones). The vast majority are well-enough documented that I've never had a problem, and I strive to document my important libs at least this well:

https://yeelight.readthedocs.io/

It always amazes me that the Python community is okay just missing indices for their API documentation. I’m so used to Rust [1], MDN [2], Apple [3], Qt [4] starting their docs off with great indices. Obviously, those are all “commercial” docs, but just indices alone is a huge help.

To be clear, I think you’ve done an absolutely great job writing the prose — I just don’t get the cultural conventions around Readthedocs :p

(There’s still wild differences in quality between those four. It seems like documentation UX would be more of a solved problem by now.)

[1]: https://docs.rs/reqwest/0.9.15/reqwest/#structs [2]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_... [3]: https://developer.apple.com/documentation/corevideo [4]: https://doc.qt.io/qt-5/qtwebengine-index.html

What do you mean by index? This is what I think of when I hear "index":

https://yeelight.readthedocs.io/en/latest/yeelight.html

Rust does the same, as far as I've seen (although the docs are a bit too index-heavy). Do you mean something different?

Maybe they mean something more like this page https://yeelight.readthedocs.io/en/latest/genindex.html which your Sphinx setup appears to be generating but the theme doesn't seem to be linking to.

Oh, thank you, that is extremely useful to include. Too bad Sphinx doesn't make these things easy, I spent some time reading the docs to figure out how to include a link to the index and there was no reference to it. In the end, this Stack Overflow answer was the only thing I found that actually mentioned how to create it:

https://stackoverflow.com/a/42310803/28196

The default theme adds a link to it for you in the header and footer. I'm not sure why some other themes don't.

This is exactly what I was thinking of.

Thanks for pointing this out, and thanks to Stavros for promptly engaging too :-)

MDN is a wiki though, run by a nonprofit and written by the community.

Yes, but it’s backed by enough interests and money that it’s still not fair to compare to a typical FOSS or hobby project :p

Reply on news.ycombinator.com