Docs.rs: Use rel=canonical to point to the latest version
Uses the same mechanism as #74, but for a very different purpose.
A common problem using docs.rs is that it's hard to find the latest version of the docs from Google. We mitigate this by having a 'go to latest version' button, but if you land on a search result halfway down the page, the header bar isn't shown. A possible way to get better results is to abuse rel=canonical to point to /:crate/latest/:path so it will be picked up by Google.
It'd be feasible to put rel=canonical in the <head> since we inject styles there already.
74 should be implemented before this to avoid telling Google we are more canonical than the original documentation.
jyn514
All 13 comments
Linking https://github.com/rust-lang/docs.rs/issues/1120 as related. I'll note that the "go to latest version" link is part of the menu bar, which is pinned to the top of the browser window, so it's always visible even when mid-page. On mobile it's just a yellow triangle with no link, which is a bit confusing.
jsha
on 25 Oct 2020
Another thought on this: Right now, even if you click "go to latest version," you'll get a redirect to a page with an explicit version in the URL. I think before working with rel=canonical, which is hard to see if it's working, it would be beneficial to make it so the latest link for each crate (e.g. https://docs.rs/ureq/latest/ureq/) doesn't redirect to a specific version, but loads a copy of the latest docs for that crate. That way each crate's docs have a stable URL that can gradually accumulate ranking. I suspect Google will never consider a URL canonical if it always redirects somewhere else.
jsha
on 11 Nov 2020
Make it so the latest link for each crate (e.g. https://docs.rs/ureq/latest/ureq/) doesn't redirect to a specific version, but loads a copy of the latest docs for that crate
I'm really hesistant to do this, that will mean the caching from CloudFront is wrong and won't be invalidated when a new release is published.
jyn514
on 11 Nov 2020
We could do a CloudFront invalidation of /{crate}/latest/* every time a new version is published.
pietroalbini
on 11 Nov 2020
Here's the pricing on that, which seems reasonable: https://aws.amazon.com/cloudfront/pricing/
No additional charge for the first 1,000 paths requested for invalidation each month. Thereafter, $0.005 per path requested for invalidation.
And from https://aws.amazon.com/blogs/aws/simplified-multiple-object-invalidation-for-amazon-cloudfront/:
An invalidation path that includes the “*” character incurs the same charge as one that does not.
jsha
on 11 Nov 2020
By the way, this approach would help with another developer experience issue: For crates I use a lot, I often find them by opening a new Chrome tab and typing a few characters of the name, then selecting them from the history portion of the Omnibox. Right now that takes me to a specific version - but it becomes outdated once a new version is released, requiring an extra click to get to the latest version. And because Omnibox scores by number of visits, it can take a while before the latest version is the top choice. If most user navigations go to the "latest" URL, their autocomplete suggestions are more usable.
jsha
on 11 Nov 2020
Right, but it also means that links to docs.rs/:crate/latest/module/x.html can break silently when a new version is published. I guess people can still use a specific version if they want to, though? I'd want to first fix the bug where clicking on the version number takes you to the root of the crate instead of the page you were on.
jyn514
on 11 Nov 2020
Those links should be mostly stable across semver minor and patchlevel revisions, since removing or renaming an item would be an API break.
jsha
on 11 Nov 2020
latest doesn't care about patch versions though - it always goes to the latest version that's not a pre-release.
I'm not saying we shouldn't do this, but we should take some care to make sure it doesn't make the user experience worse.
jyn514
on 11 Nov 2020
latest doesn't care about patch versions though - it always goes to the latest version that's not a pre-release.
Yep, that makes sense. To flesh out the idea more: The "stable" URL for any given major version could be like docs.rs/:crate/v2/module/x.html (representing the latest release within that major version), with docs.rs/:crate/latest redirecting to to /:crate/vX, where X is the latest major version.
Another approach would be to not worry about major/minor versions, and offer permalink icons next to all internal anchors. The permalink would go to whatever the latest version is at that moment in time. This is similar to what GitHub does when you highlight a specific line of code and it offers a permalink in the ... menu to the left.
jsha
on 11 Nov 2020
This is similar to what GitHub does when you highlight a specific line of code and it offers a permalink in the ... menu to the left.
OMG I'm so mad, I've been doing that by scrolling to the top, opening the commit in a new tab, and pasting the commit in place of master. That's so much better!
Yeah, opt-in permalinks sound like the right way to do this.
jyn514
on 11 Nov 2020
OMG I'm so mad, I've been doing that by scrolling to the top, opening the commit in a new tab, and pasting the commit in place of master. That's so much better!
Yay, so glad to have introduced you to this! There's even a keyboard shortcut: y.
jsha
on 11 Nov 2020
I also think opt-in permalink is better.
pietroalbini
on 12 Nov 2020
Related issues
Nemo157
·
4Comments
nagisa
·
4Comments
lopopolo
·
5Comments
pietroalbini
·
4Comments
Nemo157
·
5Comments