3 ms·
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
by inglor 8y ago
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 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.
- StavrosK 8y agoHmm, 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/ https://yeelight.readthedocs.io/
- wwright 8y agoIt 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 https://docs.rs/reqwest/0.9.15/reqwest/#structs [2]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_... [3]: https://developer.apple.com/documentation/corevideo https://developer.apple.com/documentation/corevideo [4]: https://doc.qt.io/qt-5/qtwebengine-index.html https://doc.qt.io/qt-5/qtwebengine-index.html
- StavrosK 8y agoWhat do you mean by index? This is what I think of when I hear "index": https://yeelight.readthedocs.io/en/latest/yeelight.html 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?
- mjw1007 8y agoMaybe they mean something more like this page https://yeelight.readthedocs.io/en/latest/genindex.html 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.
- StavrosK 8y agoOh, 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 https://stackoverflow.com/a/42310803/28196
- mjw1007 8y agoThe default theme adds a link to it for you in the header and footer. I'm not sure why some other themes don't.
- wwright 8y agoThis is exactly what I was thinking of. Thanks for pointing this out, and thanks to Stavros for promptly engaging too :-)
- inglor 8y agoMDN is a wiki though, run by a nonprofit and written by the community.