Affects: \Spring 5.2.2
I hope this is the right place to report issues regarding the documentation.
It seems that the documentation of spring-framework core is not parsed correctly and the chapters towards the end (e.g., about validation) do not appear in the index. See https://docs.spring.io/spring/docs/5.2.2.RELEASE/spring-framework-reference/core.html .
Comment From: quaff
It seems fixed already. See https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html
Comment From: snicoll
Thanks for the report @karge-itestra but the latest release in the 5.2.x line is 5.2.8.RELEASE and that issue has already been fixed. Please consider checking the latest bug fix before reporting an issue. There is also a simlink available per generation, e.g. https://docs.spring.io/spring/docs/5.2.x/spring-framework-reference/core.html.
Duplicate of #24138
Comment From: karge-itestra
Thanks @snicoll for the clarification. I was not aware that documentations for release versions like 5.2.2 remain unfixed if there is a newer bugfix version. I see that there was a discussion in the other issue. Taking this into consideration, I wonder why you even have documentations for those versions available front and center, instead of hiding them away for reference purposes and only give access to the 5.2.x version.
Comment From: snicoll
Not sure what you mean by "front and center". Please refer to the issue I've referenced where this particular topic has already been discussed.
Comment From: karge-itestra
Sure, let me explain.
Often, when using a search engine, people will land on old versions of the documentation. My intuition was to just remove the part of the URL after the version to obtain https://docs.spring.io/spring/docs/ , and browse for the version that I am using in my project. This is the 5.2.2.RELEASE. From there it is not very obvious that the 5.2.x version is preferable to the 5.2.2 version.
Also, the URL https://docs.spring.io/spring/docs/current/spring-framework-reference/ states at the bottom that it refers to the 5.2.8.RELEASE of Spring, so I assumed that it shows the concrete version and not the .x version. Since /current/ seems not to be a stable link to share, users might be tempted to share the concrete version link, as @kriegaex said.
Last but not least, also the page https://spring.io/projects/spring-framework#learn links to concrete versions of the spring documentation. At some point, it surely also pointed to the 5.2.2.RELEASE version. Anyone referencing the documentation from there will probably have a fixed link instead of the 5.2.x version link.
All that might seem rather nit-picking, but since old versions of the documentation are not fixed, and since I am not the first one to stumble over such an issue, I suggest to reconsider either fixing, removing or at least moving the outdated documentation and re-routing visitors such that the confusion has an end.
Comment From: bclozel
We understand that serving documentation with rendering issues is far from ideal.
Right now our documentation model is about building and shipping the code and the documentation together. For the same reason we don't change JARs for a released version, we're not updating the documentation, which is merely the docs artifacts deployed on a static server. Maybe one day the Spring projects will adopt a widely different approach, but this is not the case right now.
We're carefully looking at browsing habits and SEO and we're constantly trying to improve the situation. People have very different behaviors - some bookmark the /current links, follow the links on the project pages, or just browse the /docs/ root like you do.
The solutions you proposed all have significant drawbacks that we don't want to inflict on the community:
- Fixing the docs: this means breaking the promise of immutable artifacts and asks questions; where do we draw the line? Typos only? improvements? What about behavior changes? How do we implement that in practice in our development tasks and community contributions?
- Removing the docs and/or redirecting to new docs: removing old versions means that we're removing information about specific Spring versions; how did Spring behave? What was supported at the time? I'm sure that developers maintaining an heritage application on an old Spring Framework version would not like us to remove those docs, or even redirect their browsers to newer versions.
We are instructing search engines to consider the latest versions using Canonical links and we're currently trying to improve the SEO situation. But again, it seems that in this case this wouldn't have helped. Right now creating some frustration for community members when docs are broken on a particular version (which rarely happens) is the price to pay - I think it beats the alternatives.
Comment From: karge-itestra
I hope I am not too annoying by making one last suggestion: If you are not fixing the content, you could at least use the framework that you already have around the actual documentation content and point to the newest version, indicate that the version one is currently looking at is outdated or providing a chooser for the documentation version.
As a reference:
JetBrains does this: https://www.jetbrains.com/help/idea/2020.1/discover-intellij-idea.html#developer-tools
Apple does that with some of the legacy documentation, too: https://developer.apple.com/library/archive/navigation/ or https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/APFS_Guide/Introduction/Introduction.html#//apple_ref/doc/uid/TP40016999
Comment From: bclozel
@karge-itestra yes we're already considering this option amongst other things. Thanks!