Reposting from thread Where to flag (small) problems in User Guide? where the discussion derailed a bit from the original topic. The main question is whether we should have
docs/latest or similar as an alias to docs for latest version.
This provoked some discussion on whether we should change how we serve the docs to improve indexing.
Disclaimer: My understanding of SEO is superficial from running several hobby/non-profit sites, I may easily be wrong about stuff.
Some points to recap from the original discussion + my commentary:
@mitzimorris noted that
we have “unversioned” links, e.g.: “https://mc-stan.org/docs/stan-users-guide/index.html ”
this redirects to latest by virtue of a script which rewrites the redirects every time we do a release.
I see two potential reasons why this proves insufficient:
- Since people are redirected, they copy-paste the target (versioned) link when sharing on the web. So all/most of the links found around the web are to a specific version.
- My understanding is that Google will follow the redirects and index the target of the redirect (counting all “unversioned” links as links to a specific version). This means that even if the Google robot enters the docs via an unversioned link, it will see all further links as versioned. Also, speculatively, even if everybody used the “unversioned” links, those would count as links to older versions until the sources/the links themselves are reindexed which may take time.
As an alternative, we could use an alias, i.e. that today, under
docs/latest, there would be the same content as under
docs/2_21, except that all links within documentation would also link to
docs/latest, while all links under
docs/2_21 would keep pointing to
docs/2_21. (if all our links within documentation are relative, this could be achieved via a single
Alias directive in Apache configuration).
This can improve search results in exchange for a risk of breaking links as the docs are updated… Additionally, people would need to take care to share version-specifc links when this is necessary, while now care is needed to share a link to the latest content.
@mitzimorris further noted that
Google suggests “canonical links” - would this work?
Which I don’t think is a right abstraction -
docs/latest is semantically different from
docs/2_21 as the latter is considered to be final and unchanging while the former should update and it would not therefore be useful to tell Google to treat them (temporarily) as the same page.
Final note from @mitzimorris:
perhaps it’s a third order detail, but a distinct URL for ‘latest’ would lose having the version in the URL. by contrast, in Boost, clicking on the “take me to latest link” brings me to a versioned URL - e.g. - search “boost regex” shows 1_66 -
clicking on the “take me to latest” links takes me to:
It is true that we will lose the version from most URL and there is a tradeoff. When I read an old blogpost that links to our docs, do I want to actually see the latest or the then-latest version? (hard to say IMHO). And do we care about latest docs being high in google results?
In the wild, I’ve seen both approaches, for example Elm, has
latest as an alias. For example: https://package.elm-lang.org/packages/ianmackenzie/elm-geometry/latest/ Version appears in the URL only after you explicitly click a specific version. Googling for “elm geometry” shows me the
latest link on top, which brings me to version 3.1.0, even though it has been released just a few days ago. The Google result actually has wrong title (says its version 3.0.0), so the page was not reindexed since 3.1.0 release.
As Mitzi notes, boost doesn’t do this, they have
release as a redirect to 1.71 (as of this writing) and when I search “boost regex” the top link is for the 1.66 version.
Also related, @nhuurre noted that
When I look at Stan Reference Manual page I don’t see any indication that it’s old. The Overview page says version 2.18 but doesn’t tell how recent that is or where to find the other versions. Shouldn’t the old docs link to the latest version?
Which I think is great for both redirect/alias approaches!