Docs and Addons should display the release version by default

[cubistico]

Problem
Versioned docs display Version: latest by default, but the latest version refers to the current development version. Normal users will usually install the latest release, therefore the docs for the latest release should be displayed by default. Failing to do so causes inconsistencies between the installed software and its documentation.

Solution
Docs should be displayed for the latest release by default.

Example
A real-world example which I actually ran into can be found here. In short: I opened an issue because the MAX! binding in a fresh install of the latest release would not work as described in the docs. It took the help of others plus 5 days in time just to find out that both, the docs and the binding, were correct, but I wasn't aware of the fact that the version of the docs displayed by default as Version: latest does not refer to the latest release version, but to the latest development version, and that I had to select Version: 2.3.0 to see the correct documentation. This was a problem because the Item definition had changed from Number to Number:Temperature after the release version of the binding, so when cross-checking the Item type with the docs, I was sure they were correct.

I'm quite convinced that the average user would normally not even notice the dropdown.

[Confectrician]

Hi @cubistico,

We have talked several times about the versioned docs and the decision to display the latest docs version was made on purpose in those disussions.

I will see, if i can link the corresponding issues/PRs here.
There were reasons to choose this way, but i cant remember them now.
Maybe this is a topic for @kaikreuzer too.

BR
Jerome

[Confectrician]

After some research i have found this #520 (comment) which states the latest stable as website/docs root.

@ghys can you remember, if we decided to diplay the latest version on purpose?

[Confectrician]

Also related #619

[cubistico]

Quoting @kaikreuzer from #520 also (the comment before that):

I thought to remember that we once agreed that the entry "default" path (docs.openhab.org) should simply be used as an alias that will forward to docs.openhab.org/2.1 today and docs.openhab.org/2.2 tomorrow, while the latest snapshot is where it is today.

This sounds to me as if the default path should always point to the latest release, if I get it right. However, the later comment seems to confirm just the other way round?

I'm not convinced yet! :-)

[Confectrician]

Yeah i have rad that too, but we have to make a difference here.

I agree with kai on the path, but that doesn't mean that we couldn't redirect to version 2.x first while opening the website.

[rkoshak]

I ran into this again today and have a couple of times over the past few weeks. A user installs or upgrades to OH 2.3, reads the docs and tries to apply something that wasn't implemented until after the 2.3 release. Users, particularly new users, don't realize they are looking at the docs for the snapshots by default as opposed to the latest release.

Since the users of the snapshot should know better but we can't expect the new users to know this I strongly believe the default version should be the latest release, not latest.

[Confectrician]

I have changed the title.
Same problem goes for the addons too of course.

Hopefully @ghys can change that in the vuepress settings somewhere.

[cubistico]

Any new insights here?

[ghys]

@ghys can you remember, if we decided to diplay the latest version on purpose?

Yes we had a discussion about that once but I can't seem to find it again ;) I'll keep looking.
Versioned docs are still a issue since the current solution is a "hack" and involves manual work.
See #700 (comment)

[ghys]

Also #695 (comment)

[Confectrician]

We have made several changes to the docs and version selectors.

Further information can be found here: https://community.openhab.org/t/important-changes-to-the-documentation-versioning/122369?u=confectrician

[ghys]

It only took 2.5 years ;)

[cubistico]

Finally! \o/