Add link to latest current version in the reference manual

[maciejwalkowiak]

Search engines results often lead to old versions of Spring Framework reference and it is becoming a habit to go to address bar and change the version in the URL to current.

As I imagine it's not straightforward to optimise reference website for promoting latest current version in search results, one solution I have in mind is to add for every version older than current an information like:

This is the documentation for an older version of Spring Framework. If you’re looking for the current documentation click here.

Sample how it is done in VueJS docs:

Ideally it would link to the same page/section of the reference or redirect to reference home if section does not exist in the latest current version.

[rstoyanchev]

If you're looking at some 4.3.x version, or even older, would you consider current to be 4.3.26 or 5.2.3? Needless to say there is quite a bit of a difference between the two.

Generally when using a search engine, you should see links that point to the "current" Spring Framework reference, https://docs.spring.io/spring/docs/current/spring-framework-reference/. If that is not the case it would be useful to know.

For anything else pointing to a very specific version, it's not clear if the intent is to actually point to that branch or not.

[maciejwalkowiak]

In such scenario I would consider the latest stable - 5.2.3 - to be current. If I'm stuck on older version I would be most likely searching explicitly for this version.

In this example, first result links to 5.0.0-build-snapshot, second result to 4.1. There's no easy way to find out which is current just by looking at search results.

[rstoyanchev]

Thanks for the example.

Doc pages have a "canonical" header pointing to the "current" version but in this case, the canonical reference is a 404 (oops!). I guess the rules for adding canonical references to requests are brittle because of structural changes. We can and will address that issue, reviewing all rules for canonical links, but we'll also take some further steps.

Re-think SEO strategy for doc pages, e.g. to prevent indexing of older versions, e.g. snapshots and duplicate maintenance versions, but we've some differences of opinion on whether to index "current" only or also major/minor versions. We'll have to do some homework on SEO for multi-version doc pages, but also suggestions or pointers welcome!

Consider drop-down that lists the latest for currently active branches.

SEO updates should ensure you arrive at "current" when coming through a search engine. A drop-down with links to the docs for currently maintained branches would help when following a link to a specific version.

In the mean time, check for the "current" alias in the URL and/or manually switch to it.

[maciejwalkowiak]

I made a Chrome extension that partially addresses this issue: https://github.com/maciejwalkowiak/spring-docs-read-latest-extension

[maciejwalkowiak]

Update: extension is now available in the Chrome Store https://chrome.google.com/webstore/detail/spring-docs-read-latest-e/ccmccpfomgfkbcbfeahhjecddjajhipk?hl=en&authuser=0

[naiyerasif]

I particularly like the way Postgres handles this. They list the versioned pages for which the docs apply and provide a link to the current version.

https://www.postgresql.org/docs/8.4/functions-window.html

This may be a bit tricky for Spring though since the docs on the same page may address a lot of usecases which may apply to a wide range of versions which may be cumbersome / not much relevant to list.

[rstoyanchev]

@maciejwalkowiak I'm happy to say that this is finally coming as part of the switch to Antora in #29705. You can browse what that looks like at https://docs.spring.io/spring-framework/reference/.

I will close this issue as superseded by #29705, but feel free to comment further.

[maciejwalkowiak]

Fantastic news @rstoyanchev! Love it. One thing I noticed - switching between Java to Kotlin happens locally only to a single snippet, unlike in old docs where all snippets change at once (which makes sense i believe).

[rstoyanchev]

This has been updated so that all snippets change. Thanks for the feedback.