This thread has 2 parts, one talking shortly about new content and the later focusing on the reference handling (the main topic).
As some of you may have noticed some new content has arrived to the Ruby track. 3 new concepts (case, symbols, ranges), which aimed to strengthen the fundamentals concept of the track. And one concept has been restructured conditionals.
So for the main topic of the thread. The reference handling, at the moment references are quite spread out, using various different patterns/methods. My hope that this can be standardized to a single pattern. A majority of the most used docs can be found here: Documentation (ruby-lang.org). In the docs I mentioned above, have I used Home | Ruby API (v3.2) pinned to the latest official version. But I feel like it could be a discussion of how our docs should be aligned, so from a student, mentor (and maintainer) perspective how should we use sources/references, and which sources should we use? For the API should we pin it to a certain version or should we use the latest official?
I’ve never used Ruby API before, but as it’s supported by Ruby Central, and it seems to be more readable and accessible, I’d be a fan of using it.
It seems linking without a version auto-redirects to the latest official version. So is there a reason not to do that, rather than to pin to a version? (e.g.
https://rubyapi.org/o/string). I think I’d be in favour of that.
Ruby API is good when you want to focus on a few of the parts of Ruby, rather than have the full documentation available. I have used it for specific focused things.
To be clear, yes, you can get to Object or Kernel, though not featured on the landing page. Discovery is not as good, since it does not expose these things readily (you have to know what to search for), so discovering (and even recognizing) what is in core and standard library is difficult there.
Otherwise I generally used ruby-doc.org, while encouraging local documentation generation so that the documentation is guaranteed to be current version being developed for the user reading the documentation.
The reason why you might want to pin is because that means the source stays the same as once the article was written. I have seen places like Wikipedia link to the way back machine for this exact purpose because they want to link the source when they gathered the information and can be sure as of writing the source stays true.
The negative part is the maintainer burden of having to update links and the user may get something that is not true to the current state.