There was a pretty valid comment on another thread that search engines will often pipe you to API docs for older compiler releases. This is definitely something that has hit me before. With breaking API changes in the lead up to v1 consistency here, particularly for people new to the language, has a lot of value.
I’m unsure if there’s anything that can be done from an SEO side so that the latest docs are always prioritised. Regardless of what’s possible there, a feature to accompany this that would be incredible for usability is a banner alerting people when they’ve landed on a potentially out of date version along with a link to the latest.
To keep the docs builds static and prevent the needs for changes to the core doc tool inserting this via a CDN may be a neat solution. Unfortunately that side of infrastructure is not open for contributions on github, but if any of the core team happen to be reading this it would be a useful addition.
One solution would have been to have the current releases docs on the same url.
As most people would want to find that, google would learn to point them to the current-release documentation.
In addition there could be the “versioned” doc urls in case you need a specific version of the doc.
The problem with this is that it would take a while (if even possible) to have google notice the “new” documentation url and forget the old ones.
Both of those are already in place. If you swap out the version in the URL for latest, this will 302 you over to the appropriate version. This issue is that redirected URL is not indexed.
Hey @kim, thanks for raising attention.
This topic has been on the table for a long time. Far too long IMO…
There are actually quite a few issues and PR trying to deal with that. The central discussion is probably in #5952, which also discusses some of the issues we’re having and it’s really not clear what the ideal strategy is.
Besides SEO, we also need to enable better navigation in the API docs. I’ve actually just pushed some new commits to #8792 which would add basic version display to the docs page (more in #4754). And in #7011 (comment) I’ve detailed a plan to add links to other versions and make readers aware when they’re browsing outdated API version docs.
Nice! As with most things in this community, I should have assumed there was already deep discussion on this. I’ll be closely following those GH threads.