The Rails community has an impressive ethos surrounding things like usability that I have come to appreciate in a short period of time. But the API docs at http://api.rubyonrails.org involve so much scrolling around and searching, that I actually think I must be missing something obvious.
For example, if I search for “rails find”, I get:
http://api.rubyonrails.org/classes/ActiveRecord/Base.html
The only links at the top of the page are labeled as source files, which usually link to bare-bones API indexes, and the base class. Helpful sometimes, perhaps, but not usually. There isn’t even a link to the home page or a search box. If I want methods, exceptions, or any other subheading, I have to scroll or search for it. The verbose descriptions at the top are useful, but only if you take the time to hunt around for what you’re looking for in prose — again, no links to subheadings. Things are marginally improved with the search bar, which can only be accessed by visiting http://api.rubyonrails.org/ directly (or locally), and usually returns lots of unhelpful exact-text matches.
I realize they are community-maintained and that I have the freedom to author something better if I don’t like it, but I’m assuming that the RoR gurus have already thought about this and decided that the current API docs are perfect! What am I missing? Why are the docs missing the elegance of so many other Rails components? Are there smarter ways to use them?
(I know there are alternatives discussed here and here, but the latest API from railsapi.com is always preferable and faster.)
I found that it just took time. Once you get to know what it is you’re looking for, you’ll know which module/class to start looking in and get to it much faster.
Definitely keep your search simple. If you know the method you’re looking for, type only that into the search pane. Always start at http://api.rubyonrails.org – it has a fuzzy finder that quickly searches through all the docs and it sounds like you’re not taking advantage of it. It’s great stuff.
For example, above, you searched for ‘rails find’. I’m assuming you’re looking for a description of the ActiveRecord::FinderMethods – if you type just ‘find’, the first result is exactly what you need.
If you find that the straight up API doesn’t do it for you, go to the guides – http://guides.rubyonrails.org – they’re a little bit more verbose with some explanations of what’s going on where.
If that fails, use Stack Overflow, google, etc..
Good luck!