Link to "Latest" in version selector

[tadman]

When leaving advice about how to use a particular method somewhere that needs to be long-lived it'd be nice to have a link to the "Latest" version of Ruby as an option. This is not "Master" which could be confusing since it's the upcoming version.

Having a more permanent version of a link to a method or class would help a lot in that case.

Right now URLs are of the form:

https://rubyapi.org/2.7/o/array#method-i-sample

A permalink version might be of the form:

https://rubyapi.org/stable/o/array#method-i-sample

For the latest stable version, whatever that happens to be at the time.

[AlexWayfer]

I think it's a bad practice, because in the future, when this link can be opened, there may be not such method, and receiver will not understand what did you mean. That's also the reason why when you give a link to a code in a repository — it's better to replace master in the URL with an actual commit hash.

But you can get such link on Ruby API, just remove a version: https://rubyapi.org/o/array#method-i-clear

[tadman]

That's a good point, but having a permanent link solution would be very helpful. If something gets removed it'd be a lot better to show "Removed in Ruby x.y" and link to the last version of the documentation than to 404.

This is all to make links as durable and long-lived as possible. It could also help from an "SEO" perspective so the results aren't cluttered up with various versions of exactly the same thing since using meta tags you can steer them all to the generic version.

When trying to find documentation normally using a regular search engine I have to be exceedingly specific about the version, like "ruby array compact 2.7.1" or I'll get some unbelievably antiquated results from the main Ruby docs.

That /o link is nice, though, so that's handy!

[AlexWayfer]

If something gets removed it'd be a lot better to show "Removed in Ruby x.y" and link to the last version of the documentation than to 404.

So, to display such text it should be for any existed at some time method, a page can be over-bloated. And if you want to render such text only for requested method from URL anchor — it can be difficult, but, of course, possible. By the way, URL anchors work in such way that this is just auto-scrolling on a page, there is no 404.

Also, another point: what if you're referencing on method #foo via non-locked Ruby version and commenting "sorry, but this methods accepts only bar, we can't pass baz", but then Ruby Core team noticed it in some way and added baz for next Ruby versions, and some people come by your link and don't understand you, because they see that #foo accepts baz too. Smart part of them can check #foo in the available Ruby version at the moment of your comment, but it's harder.

There're version locks of dependencies (and Ruby is dependency of your code, your discussion) not "just because", it's important for guaranteed working (including people understanding in discussions). So, it's still bad way (I'm sure) for your examples. The only way where I can use RubyAPI.org links without Ruby version — browser autocomplete, so when (once in year) a new Ruby version released — my links stay unchanged. But it still can be a problem when I use some method or arguments from this latest documentation in non-updated (with previous Ruby version) project, I have to be attentive.

This is all to make links as durable and long-lived as possible.

I don't think that mutating links "long live". If you're using product "Foo" (IDE, git-client, browser, something else… Opera, for example!), and then there is "Foo 2" (or "Foo X") — is "Foo" still living? In fact, yes, but this is not that Foo to which you're used to: there can be new things, there can be no other things, etc. So, in software "long-lived" is when some version of some software works even after a time.