I think most of us don’t work with the latest and greatest ruby on rails version. On api.rubyonrails.org, it would be nice if there were a way to switch between versions.
For example right now, if you’re visiting ActiveRecord::Associations::ClassMethods off google, you would need to change the path by hand to ActiveRecord::Associations::ClassMethods in order to view 5.2.3. IMO this is too much work.
This exists! https://api.rubyonrails.org/v5.2.3/ will lead you to the 5.2.3 docs.
I agree that it isn’t very discoverable, though.
This is one of the strengths of apidock.com. They have a version switching widget at the top of each doc page which in addition to allowing quick switching gives information about what version it was introduced or removed.
Can you tell me more about what you like about apidock? I’ve always found its UI pretty painful, but I’m interested in hearing more about what you perceive as its strengths.
I don’t especially like it. I often find myself there because it gets better SEO hits than the rails docs do (sometimes). Just the version switching by a single click seemed relevant here.
One thing. The google search links to the rails docs jump into the frameless landing page which lacks context and easy navigation. The frameless nav discussed in Rails API Guides navigation would solve this.
discuss converted my urls, the second one was pointing to 5.2.3.
apidock shows the version where the method / class you’re looking at was introduced or removed, for example:
Honestly a Dropdown at the top to let you switch versions would work just as well
APIDock annoys me so much. It consistently gets the highest Google results, and consistently shows you examples that are years out of date.
Same.
Why is APIDock so much better at SEO juice than the “official” documentation? Is it possible to outcompete it? IME the existence of SEO-optimized, out-of-date examples that look official hurts people who don’t know how to tell out-of-date docs from up-to-date ones.
There is an open PR for adding versioning:
Apidock has pages for each method. The official docs has a page for each class. So if you search for “activerecord has_many” the Apidock has a page with the title tag:
<title>has_many (ActiveRecord::Associations::ClassMethods) - APIdockM</title>.
This is ranked higher by SearchEngines…
And with the current frame-based layout it’s a bit hard to deep link to pages. Copying the url from the location bar doesn’t work and the url to the actual page doesn’t contain the navigation.
That’s an excellent question. I can’t say that they are doing anything better than the “competition”, and they don’t have an advertising-driven strategy, either, unless you count the “FlowDock” link at the bottom of the page, there’s no serious advertising going on here, so they don’t have a bias toward driving eyeballs to the site.
Here’s what I see them doing well, in no particular order:
Unrelated to search juice, they have some very clever UX features. I love looking up at the timeline view at the top of each page, and seeing whether the feature I have hit upon is in the current API or not. So many things die between major versions, and it’s hard to recall, if you’ve been doing this as long as I have, which ones are still alive. This is a quick mnemonic to let you know immediately, before you dig into the depths of the documentation.
Dings against it: it’s not always immediately obvious whether a piece of advice is relevant any more. Even if the feature is still live in Rails, its implementation may have changed dramatically over the years, moved from one part of the API to another, have a completely different parent class or module, and the specific advice given in a user comment may be wildly off-base as a result. It was true at one time, and now, it’s worse than bad. Not sure how we could make a better approach to this. Perhaps it’s as simple as a set of pickers next to the comment form, with Major, Minor, and Patch values to annotate each user comment. That would give you a fighting chance.
I would love it if someone related to the APIDock project would give us a peek behind the curtain. I’d like to know if this is someone’s labor of love, or if there is a commercial effort behind it, and if so, how much of one.
Walter
I regularly work on older rails projects and it is an inconvenience not being able to easily switch to a specific version of the api docs. Of course, once I’ve got the right url, I can either bookmark it or just take advantage of the url history in my browser. But still, the ability to easily switch from the current api doc to a previous version would be very helpful.
I second this for the guides too. Wanted a refresher on fragment caching, did a quick search for “rails cache”. First hit shows Ruby on Rails Guides: Caching with Rails: An overview.
Title looks good, let’s click into it. Wait… It’s for Rails 3.2. These guides probably don’t work anymore, so let’s find the guides for Rails 5.2. Now where’s that switcher…
Is this still a discussion? Me and my colleagues regularly work on outdated rails versions and we would like to know what/where/why things originated, got changed, got deprecated, got removed.
Why was https://github.com/zzak/sdoc/pull/94 closed it seemed to get the job done.
I would be more than happy to work with someone from the rails team and prepare an APIDock style “versioning toggle” or something else that we can use in the docs.
