maybe (probably) I just missed it: Is there any way to compare the documentation of version 4.0 with the current version (3.4.4) and highlight the changes?
Of course the changes are all well documented here. But it is quite tedious to track all the changes there. From my point of view it would be easier if the changes were highlighted in the documentation (or there was a version with highlighted changes). This would allow a “normal” user to quickly understand if and what changes and innovations there are in the bindings, UIs, etc. that are used.
For example, I only found out by accident that there is now an INPUT function in the sitemap.
you already mentioned the release notes, where all changes done are listed, but you are right that it’s tedious to read the full release notes, however this is the only way to learn of all changes.
BUT … With every new minor or major release there is a blogpost on the openHAB website where selected changes are highlighted, e.g. openHAB 3.2 Release | openHAB.
We have already started working on the 4.0 release blog post, which will definitely highlight the biggest changes in all parts of openHAB.
thanks for pointing out the blogpost. I was thinking of some kind of “markup” (like in Word) for each individual page of the documentation. I found a site on the internet that compares the content of websites and shows the changes (that’s how I came across the change in the sitemap). But as I said, this is just quite tedious.
I have no idea if there are any tools that create something like this automatically. But if there are other users who find a markup helpful, maybe you can put it on a wish list
openHAB is an open source project made up of volunteers. If you think this is an important addition to the documentation, you are welcome to contribute!
I know of no tool that would do this automatically and frankly it would only capture a certain class of change. For example, if a page moves to a different location in the hierarchy how do you show that?
But the version of the docs for each release gets preserved. So you could open the old version and the new version of the docs webpage side by side and compare the two that way. In the upper right corner you’ll see
which will let you choose the different docs versions.
Note that “Latest” mostly follows the snapshots, not the milestone releases.
Writing/editing is my day job, so I’ve given this a lot of thought.
As Rich points out, this is always the challenge with updating any document, including in Microsoft Word, Google Docs, or any content-management system. It’s easy to see light edits, but as soon as there are structural changes it can become difficult to follow–particularly if you aren’t familiar with the original document.
You could look at the Github commits for documentation updates, which would show specific tracked changes, but I suspect that would be tedious in a completely different way.
Though that would only show those changes that are end user facing. Lots of changes are internal or only impact add-on developers and the like. But any PR on the docs repo is almost by definition going to reflect a change in the user facing parts of OH. It might be worth doing after all.
But definitely look to the announcements and blog posts that come with a release first.
I will give that a try. Fortunately, my monitor is big enough for that
You are absolutely right. I’ve already had that experience, too. Depending on the extent of the changes, you always have to decide on a case-by-case basis whether a markup will help you or not. But if it depends on the individual case, it is of course difficult or impossible to create a consistent structure. That’s a pity, because actually I didn’t think my idea was so bad
I’m not very familiar with github unfortunately, but I’ll look into that as well. In the end, only the changes that affect the end user are relevant to me.
Tracking of changes would have to be done simultaneously (cf. MS Word - no, I definitely don’t recommend it for openHAB ). Comparing different document versions post creation will not work reliably.
Github can show you all the differences between branches of a repo. I couldn’t find branches for the exact versions you want, but the ones I selected are probably fairly close and you can play around with the selections at the top.
Not sure if it’s exactly what you’re looking for, but it’s probably the easiest way to see text diffs of a whole repo.
