3 ms·
Here's my hot take on Ruby (as a big Ruby fan): Ruby libraries in general have bad documentation. Some other languages I've worked with in the same time frame t
by vlunkr 5y ago
Here's my hot take on Ruby (as a big Ruby fan): Ruby libraries in general have bad documentation. Some other languages I've worked with in the same time frame that typically have better docs are node.js/regular js, Python, Golang and Elixir.
For many gems, all you're going to get are a couple of examples in the readme. If you're lucky, there will be some generated rubydocs, but quite often that isn't helpful either, because it's just a list of method names with no descriptions, or it's not clear at all which pieces are intended to be the public API. Even Rails has this problem sometimes. The guides are very good, but when I need to do something off that beaten path, I'm often reaching for stackoverflow.
- mrinterweb 5y agoMy favorite documentation trick for ruby is to run your own doc server locally documenting the versions of the gems you are using. I use the "yard" gem. yard server --gems --reload For rails and ruby docs, I use Dash (on Mac). I use Dash for local docs for other languages and systems as well. Just a handy tool for local docs.
- dragonwriter 5y ago> Here's my hot take on Ruby (as a big Ruby fan): Ruby libraries in general have bad documentation. Some other languages I've worked with in the same time frame that typically have better docs are node.js/regular js, Python, Golang and Elixir. JS libraries, IME, are often very bad, though there are some good ones. But, on Ruby, I would go further and say that, especially compared to Python which is so similar in many other respects, Ruby (and not just the library ecosystem,) has a very bad documentation culture. In fact, more than in libraries, this is evident in the first-party documentation available on the language homepage.
- vlunkr 5y agoI agree, JS is kind of all over the place.