Find a way to always have reference documentation updated

[manumafe98]

Yeah, I thought that the variables accept plain text, but it seems that they only accept URLs. However, I still think we should find a way to handle this, because currently, we have a ton of documentation for different Java versions – 7, 8, 9, 11, 12, 13, 14, etc. Perhaps a policy to only add documentation for the latest current version, but that wouldn't eliminate the need to update the older ones at some point.

Originally posted by @manumafe98 in #2722 (comment)

[sanderploegsma]

Here are my thoughts on this:

• The fact that some exercises link to older versions of the docs isn't a bad thing per se, as long as the applicable parts of the documentation are still compatible with the latest version of Java.
• In fact, we can choose to add the language_versions key to the .meta/config.json file of each exercise, informing the minimal Java version requirements for that exercise are. Then the policy could be very simple: if an exercise requires Java >= 8 for example, all links to the documentation could point to the documentation for Java 8.

If we want to make sure all docs always point to the same Java version I don't think there's an easy way of automating this, other than doing a find/replace on all Markdown files. Before we do so, I think it might make sense to be a bit more explicit on what Java versions are officially supported by Exercism, as the track tooling needs maintenance in order to remain compatible. So suppose that the highest supported version of Java is 17, then all docs should point to the Java 17 documentation. And whenever we add support for a new Java version, we can go through the exercise docs to update all links to the Java docs to point to this new version.

[manumafe98]

I think the second point makes more sense (for me at least), probably the latest supported version of Java isn't going to change so frequently, and when it does is going to be a easier update, than the one we have to do now.

[mattcristal]

Hello everyone,

I was going to open an issue about the lack of consistency between the Java language references. In my opinion, this is not very beginner-friendly. Instead, I would rather have all the references pointing to the same version of Java (ideally a recent one).

This is my personal experience as someone new with this language: I already had to make a decision when I had to install Java locally which version to install. In the end, I went for the 21 LTS, which was the recommended one. I believe that, in time, the person learning about the language and tools will appreciate the evolution of language and all the features that have been added over the years.

I also guess that even though older version of Java are still popular and used, it makes more sense to learn from a more modern version. Some exercises could also point out, when learning specific concepts, how things evolved historically and why. For example, today I completed an exercise on ternary operators in Java and I looked up the same concept in Python - the language I am more familiar with. I discovered that it took some years before ternary operators were included in Python.

Sorry for the long post, I just wanted to explain my reasoning and also share my personal experience.

[Utkarshya01]

Hi, I’m new to open source and learning Java.

From a beginner’s perspective, having documentation from multiple Java versions can be confusing. I think it would be easier if all exercises pointed to a single stable version (like the latest LTS), so learners don’t get confused.

Also, maybe mentioning the Java version clearly in each exercise could help beginners understand better.
I’d love to help with documentation if needed.