lsegal/yard — Issue #426: more intelligent linking
Author: dchelimsky
Created: 2011-12-10 13:24:29+00:00
State: open

Moved from https://github.com/lsegal/rubydoc.info/issues/40

tl; dr

References to rubydoc.info in other publications are usually about the subject of the docs, not the docs themselves. Since the docs improve from version to version, links within the current version should exclude the version number in the URL, providing the reader with the most up-to-date documentation for the given subject.

The problem

Documentation for any library improves over time, from version to version. If I go to http://rubydoc.info/gems/rspec-core/ and click on Hooks I end up at http://rubydoc.info/gems/rspec-core/2.7.1/RSpec/Core/Hooks. If you follow that link, you'll see, well, not much. Now go to http://rubydoc.info/github/rspec/rspec-core and click on Hooks, which takes you to http://rubydoc.info/github/rspec/rspec-core/master/RSpec/Core/Hooks. When I release 2.8, that's the documentation that will be linked to from http://rubydoc.info/gems/rspec-core/. It's not only better, it's actually existent!

The problem is that someone who is referencing these docs in a blog post or a tweet is very likely to grab the version-specific URL as/is and post it, which means it is soon linking to stale documentation.

Now one might argue that if you're referencing something you want to reference that thing, but I think that's only the case when the documentation itself is the subject of the blog or tweet. Most of the time it's the thing being documented that is the subject, in which case something is lost by linking to the version-specific doc.

Proposed solution

rubydoc.info renders the current version if there is no version in the URL. Since it knows which version is the current version, it could use that knowledge to render links differently for the current version than older versions - without the version number in the URL.

Older versions would render version-specific links. For that to work, when a new version is published, the docs for the previous version would have to be re-generated. Additional overhead, yes, but it seems like a fair tradeoff to me.

Ideally, we'd also account for links that point to docs that existed in older versions but no longer exist in the current version. In that case, we'd either need to redirect to front of the current version with some flash-like message explaining what happened, or index the old versions and find the most recent version that still has that content.