4 ms·
Coming from Java the biggest surprise to me was a lack of good API documentation for Rails and Ruby gems. Javadoc used to drive my productivity. It is quite fr
by vrepsys 13y ago
Coming from Java the biggest surprise to me was a lack of good API documentation for Rails and Ruby gems.
Javadoc used to drive my productivity. It is quite frustrating sometimes with Rails that more often than not I can't find good api docs.
Rails and various Ruby gems have very good tutorials, but sometimes no api docs at all.. Tutorials are great for getting started, but you're in trouble when when you want to do something slightly unusual.
Slowly I'm realising that to be really good with Rails you need to look into the source code of libs you're using to get a better grasp.
As an example, I wanted to find out if it was possible to do something with ActiveRecord.to_json that I haven't seen in any tutorials. Spent 10 minutes searching for docs and then looking at the code.. which in Java would have been done in 20s.
Having said that, I really like Rails and enjoy a lot of productivity gains. I just wish it had better api docs.
- Legion 13y agoThe relative terseness and readability of Ruby code makes it so that turning to reading the source code is often favored over a lot of documentation. It would be a bit more difficult to operate in the same way in a Java environment. That said, the fact that it's kind of viable in Ruby doesn't mean that it's the best thing. Ultimately, I agree with you: better documentation would be very welcome.
- josephlord 13y agoYes and source code only tells you how it does work not what it should do. I find it tricky to follow a call path through polymorphic and mixin based code.
- rschmitty 13y agoI really love javadoc (pretty sure thats what generated the AS3 docs from back in the flash days). I feel the same as you, AS3 I could code from the docs, Rails I find myself searching online Right now I'm really enjoying Dart's docs: https://api.dartlang.org/apidocs/channels/stable/#home https://api.dartlang.org/apidocs/channels/stable/#home First time I've seen omniref so looking forward to trying that out