There's lots of issues I run into with Rails docs. Off the top of my head:
When I look something up (and I'm fortunate enough to get relevant results), I often get the site http://apidock.com/rails. I'm not sure if it's even an official Rails documentation site, but it appears near the top of the search results. And very often it will say stuff like a method is deprecated but it doesn't say what to use instead.
There were some cases where the Rails API docs weren't helpful so I got help in the #RubyOnRails channel, and others agreed that the docs were lacking (sorry, can't remember what the cases were specifically).
And what probably bugs me the most, is that a lot of the resources you find online are outdated, and that just makes things super confusing. This is a problem caused by the community though, since most of the resources are on blogs, Stack Overflow, and so on. For example, many gems or products do not have docs for Rails 4. Or sometimes it's very difficult to tell if a gem is even compatible with Ruby 2 and Rails 4, because that info isn't mentioned anywhere. A few days ago I submitted a patch for the popular Rails community style guide because it had incorrect info (and it wasn't just that style guide, the same outdated info was on many blogs as well). I try to do my part by updating outdated Stack Overflow answers when I come across them.
edit: I'm a big fan of the RailsGuides (can't link to it because I'm a new user and apparently not allowed to have more than 2 links in my post). That's one area where they typically do great in terms of documentation. Though this morning I was confused because the steps for upgrading from Rails 4.0 to 4.1 didn't explicitly say that the guide was strictly for upgrading and can be safely ignored if you're creating a new Rails 4.1 app, so I had to ask on IRC.