On openHAB documentation and some more

21

@Nadahar your suggestion is that the github release note should include a link to the release blog?

2 Likes
22

For example. My suggestion is simply that it should be easy to find, and in particular that searching for “changelog” should lead you there.

1 Like
24

It often is but I do see it’s not always included.

You can use them in rules and HABot user the tags to understand what’s being asked (how many of you on this thread knew OH has a chat bot interface since OH 2.5? That’s what the semantic model was originally created for).

As I read that thread your PR appears to come out if the blue and makes major changes without any prior discussion. It would be as if someone came and completely changed the jRuby binding’s architecture in one PR. You might have some concerns and great burn, right? Maybe I’m missing a discussion elsewhere but large changes made without prior discussion and buy in from the maintainer is going to be met with resistance.

For example, I created an issue to rework the rules documentation where I ladies it an outline, invited discussion and established a task list. Then each task was individually implemented in a separate PR. I meet success with that approach.

A PR for secrets handling was started but never finished. I’m not sure why.

A self hosted git is possible and many use that including myself. And I use a 100% managed config.

In the mean time, there are tools for encrypting secrets if you want to use a public service like GitHub. Hopefully secrets handling will get picked back up.

It’s not defensiveness. My replies are to give people an understanding of what’s possible now to set a more firm foundation for discussing what can be improved. It’s frustrating to see suggestions that either ignore progress already made or requests for things that have already been implemented.

These threads end up going off the rails if they are not based in the complete current state of OH.

Here’s a new suggestion. Lots of software will throw up a dialog when there’s a new version of it. After the upgrade, it throws up a dialog with “what’s new” it a link to “what’s new”.

Since many users don’t know or don’t care to look at where OH currently posts this info what if we push it to them instead of relying on them to go find on their own.

This flies in the face of the whole help discussion above but then at least no one would have an excuse for not knowing that the blog and change log exist and where to find them.

Bonus points if it links to all the announcements and change logs between the old version and new version since a distressingly large number of people wait years between upgrades.

3 Likes
25

This was exactly the kind of thing I was “worried about” and made me reluctant to adjust the semantic tagging to accommodate the UI. Then I reassert that there should be some way to hide items in the autogenerated pages while keeping the tagging intact.

It might not be defensiveness, but I can assure you that it can come across as such at times. Regardless, there is a fundamental problem here: If anybody that should be “allowed” to make any suggestion has to get to know all the details of the system upfront, there will be very few suggestions and attempts to change things. This limits all kind of “impact” to a very few people, because only a very few people know enough to be in this position.

At the same time, I understand that it’s frustrating to deal with people that makes little or no effort to see the big picture and only wants something changed to accommodate themselves and their needs. But, there has to be somewhat of a balance here as I see it, those that do know must “help” those with initiative gain the knowledge they need to get the full picture. If they are just told to RTFM and shut up until they have thought of every detail, they will lose all initiative.

I’m not saying that’s a bad idea, it might help for some people, but I’m against being “force-fed” in general and will probably be against reading it for that reason alone. Also, it’s not certain that it pops up at a time when I’m ready to digest it - in fact, it wouldn’t work at all for me, because I need the information before I do the upgrade. It’s also unlikely that I would upgrade to every minor version, so I would still miss out.

I think a changelog, where you can clearly see what has changed between version x and version y, by far is the superior format to inform about changes. It is especially important that everything that is broken or changed is clearly stated, so that people can try to find solutions before they upgrade and things stop working. There can be other forms in addition, blogs, essays, whatever you want, and they can be linked to from the changelog as additional information, but I think a changelog-like structure should be “in the bottom” of all this.

1 Like
26

As @rlkoshak explained above, this probably isn’t the case. Which makes it more difficult to know how to deal with again. For me, the essence is that it should be very clear and obvious to everybody exactly what role it plays. That will probably “clear up” a lot of the confusion and reluctance.

1 Like
27

The documentation has gotten a little bloated. Some restructuring would help.

History lesson time.
This is a thread I opened in 2018. The documentation way back then was terrible. So many people have contributed. No one more then @rlkoshak

Also
This Thread about thee first time user wizard which culminated in a huge improvement to the first time user wizard.
I think I remember Yannick talking about templates for typical models like 1 bedroom flat or typical two story house. Or a wizard that walks you thru the semantic model setup

2 Likes
28

Yup, that exists now too. If you have no semantically tagged items, and open the model page there should be an option to " Add Locations from Template" which will allow you to select from one of three basic templates and then modify some of the locations. It will then create the complete location structure. You will still have to add extra locations to fully represent your space and add all the equipment. But between those templates and the “Add equipment from Thing”, a user starting from no semantic information should be able to get a working semantic model in probably 30 minutes or less.

Again, there was some discussion about whether to make this option always visible or only visible when there is no previous semantic model present and in the end it was decided to try it the more restrictive way first. I’m sure if someone feels strongly the other way a PR would be given due consideration.

1 Like
29

Are you intending on using HABot? If not that doesn’t matter. In Rules the actions are to get the parent equipment or location, those don’t care what tags you use, though you might.

HABot is nice and convenient for a few things but it’s not really been worked in and frankly focusing on the ChatGPT add-on rather than messing with HABot might be a better use of your time. For the most part the semantic model is used to build the overview tabs and for what ever you may want to do with them in your rules. And HABot is aware of and can use your custom tags too.

But there is a way to do that. Set the default list item widget. If all you cange is the visibility field the default widget is preserved and you don’t need to define it again.

Indeed, which is why I’m out. I’m done discussing what can be improved here or what is already implemented. Please discuss amoug yourselves. If I see something factually incorrect or have something to say about anything other than MainUI I’ll chime in. But I’m not going to be a source of discouragement. Honestly, unless someone volunteers to implement it it’s all just talk anyway so I shouldn’t care so much anyway.

We have that. We’ve had that for almost forever. We link to it in the forum, the blog, and it’s on GitHub. But you can’t find it. So what would you have us do? *Where what do you want us to post it so you can find it? You don’t want us to tell you.

I think I might just be out on this whole thread. Ping me if a moderator is needed and one of the other mods on this thread are not available.

30

I don’t intend to use HABot because I honestly don’t know what it’s about. I’ve never wanted to have a “bot” in my system, my life have enough frustration from being forced to interact with “bots” for support etc.

It does however very much matter to me what the intention of the semantic model is. If it were a “tool” reserved only for organizing MainUI, I could treat it as such. When it’s more generic, it should be treated as such - regardless of how this impacts my installation at this time. What I do there could impact future functionality, and I simply can’t know the implications. I don’t want to have to redesign things over and over again because suddenly this implicates that, and that wasn’t taken into consideration when I made my previous design. Is that really so strange? I have no idea if I’m the only human on earth that thinks like this, but to me, it feels “natural” and I would assume that I’m not alone.

Ok, that part I hadn’t understood. So, by defining a “custom list widget” and only setting visible to false I can hide them
 If I understand you correctly, it ends up looking something like this (for every Item that I want to hide):

{
	channel="xxxx",
	listWidget="oh-label-item"[
		visible=false
	]
}

This never crossed my mind, but I wouldn’t exactly call this intuitive or easy to guess. I’m pretty sure that quite a lot of people don’t know that you can do this.

Great - but how do I find it? I’ve looked through GitHub - openhab/openhab-core: Core framework of openHAB - there is no CHANGELOG file, there is nothing on the tags. It wouldn’t be very convenient anyway, since there are so many different repos to cover, but I would at least expect to find some reference to where I can find it.

If you mean the distro releases, yes, there’s something there, but it’s mostly references to issues/PRs where you have to read a LOT to get what has changed: Releases · openhab/openhab-distro · GitHub

It’s also “polluted” by all the add-on changes that kind of obfuscates the changes to “OH itself”.

Or is there something I’ve still missed? All I know is that I’ve tried to find what’s changed in the past and given up.

This is one of those comments I don’t understand. What possible intention does it have other than to discourage engagement? I thought this thread was exactly about that, discussing what could be done to improve things with the knowledge that none of it might actually happen. It’s still not “worthless” as people exchange ideas, and some of those might actually make it into something in the future. I think a discussion it itself has value, as a potential source of ideas.

2 Likes
31

I think I will be going off script here again, in the last two weeks I’ve already been reprimanded by @rlkoshak once and I’m not keen on being again, so I’ll start by saying sorry.

I think we’re discussing two different things here. One is what @rlkoshak is saying, and that’s the release notes. What’s new. I will be pretty sad if someone says that they can’t find them when I’m putting them up on Reddit all the time, and they are being put in Twitter too, they even appear in easy Google searches, as you can see:

IMG_9908
IMG_99081170×2532 295 KB

But @Nadahar is asking for Change logs which can be fundamentally different from release notes.

While both can address the same topics, change logs can (or to be differentiated from release notes, should) go into technical detail about said changes. Release notes do not.

In that sense, I believe that one would have to open the release in GitHub, and go through each PR. The information is there, simply not in an easily consumed fashion.
But does it need to be? I find it hard to imagine someone reading through information about 10 different PRs from 10 different bindings
 what is your objective @Nadahar ?

32

I feel that we’re getting stuck on a very tiny detail here now, my “wish” was that there was an easy way to see what has changed from version x to version y, so that you can see “what’s new/improved”, “what’s broken”, “what needs configuration changes”. It would work both as a decision source for whether to upgrade or what you need to do before making an upgrade, and as a source of information about new possibilities.

When I have to read through a lot of individual release notes for different versions between x and y, not being sure if I’ve found them all, I’m not confident that I have the full overview.

But, this isn’t an important point that should be made such a big deal out of. It just came up because it seems quite frequent that I myself and others aren’t aware of changes that have taken place, leading to both frustration and missed opportunities.

Edit: What I was suggesting was basically release notes in the form found here:

https://www.openhab.org/blog/2024-07-07-openhab-4-2-release.html


but a bit more condensed. Things like

One year has passed since our big openHAB 4.0 release, and we are thrilled to announce our first summer minor release of the openHAB 4.x series: openHAB 4.2. openHAB 4.2 adds a number of exciting new features, including some long awaited notification enhancements, as well as a multitude of smaller improvements and bug fixes.

With that being said, we as usual want to share our highlights and some statistics that show the activity in numbers.


doesn’t really belong in a changelog as I think of it. You want the changes, not a lot of text that “distracts” from the changes.

Then this information should be presented “chronologically” where you can scroll through multiple versions and read everything from point “x” to point “y”. All releases should be there though, I couldn’t find anything for 4.2.3 for example. It might not be much to say about 4.2.3, but then it should say that. It’s about the overview. So, basically the work is already being done when the blog entries are being written, it just needs to be organized in a “centralized place” where you can access all of it at once.

This form isn’t very helpful as I see it, because it requires everybody that wants an overview to actually read through (and understand) all the Issues and PRs listed:
https://github.com/openhab/openhab-distro/releases/tag/4.3.0.M4

But, as already stated, I don’t think it’s a big point, so don’t waste any more time on it. It was merely a suggestion to make it easier for people to “keep in sync” with what’s changing and make informed decisions.

33

TL;DR it’s hard to have the type of changes needed to the docs even when numerous consumers of the docs have complained about it. Since my life is not really that affected by whether the docs stays as it is or not, it is not a battle I’m currently willing to take on.

Prior to submitting that PR, I had been submitting fundamental functional and quality of life improvements to the Blockly environment, including upgrade of Blockly from v9 to v10, adding multi select, skin/renderer switching, standardising the copy/paste and navigation (pan/zoom) etc. So up to that point I was invested in Blockly improvements.

My documentation PR was intended to serve as a concrete demonstration of what changed, and a place for discussion. It’s easier to show what I had in mind than describing it first. It involves some removals here and there and some sections being moved. Rather than describing it, and not giving the exact picture, I chose to submit a PR so one can see exactly what the new doc would look.

Splitting it up in micro chunks would involve a lot more work and each change would miss the whole point of the restructure. The changes are interrelated and would need to be committed in one whole swoop otherwise you’ll end up with a frankenstein monster all over again.

The main issue was not the minor edits / grammatical corrections / sentence rewordings.

The main issue is the fundamental structure of the documents, and how it is so long to read. From memory it also had repetitive information that could/should be condensed and/or simply linked.

I don’t even think that my PR was reviewed as a finished / rendered documentation and evaluated as a whole as it was intended. It was simply rejected because it’s throwing out existing paragraphs, which I consciously removed for the exact reason I’ve outlined in my previous post above.

Here’s an example. Current paragraph:

image
image1856×868 122 KB

image
image1904×1754 474 KB

My proposed change in the PR:

image
image1778×1358 246 KB

I proposed to cut out (or actually moved it to the end) the history lesson and the super wordy, unnecessary text. As a newcomer, you’d have to go through so many paragraphs - in fact you’d have to scroll to the MIDDLE of the first long page of blockly doc just to get to start to see what you can do with it.

It starts with the assumption that the newcomers are complete imbeciles but at the same time, enjoy reading 1000 pages love and war.

There are so many subtle changes in my PR that (once again in my opinion) would improve the experience of reading the docs for that section that are rejected, and the status quo remained to this day.

In any case, my main point here on this discussion is that whilst there have been many complaints about the documentation, my experience shows that attempts to remedy the situation proved difficult. Maybe it’s because the current doc maintainers don’t even realise / see the problem, and are unwilling to accept (major) changes.

My rejected PR above was minuscule compared to what (I think) needs to change in the docs.

But on the other hand, I am grateful that there’s a maintainer at all. I don’t envy the role.

Quite the contrary, if someone came along with major improvements, I believe it would be greatly accepted, with due process to avoid breaking changes. And here’s the crux of the matter: the opinion of what constitute as improvements can differ, and who is in charge, matters a great deal.

It would be stupid of me to have “pride” and feel “burnt” if someone came along and created a better wheel than what I had invented. If the new thing is better, why the heck not use it? It’s not like I had to pay them for it. It’s free open source!

Case in point: since the introduction of Semantic Model in openHAB, it had been a major pain point that we weren’t able to add custom semantic tags. We needed to beg for the core maintainer to include them and that would involve a very lengthy deliberation, yadda yadda, I’m sure you know how it was.

I submitted a PR that made it possible to add custom semantic tag. It was not ideal, and sure enough, someone else eventually ripped it out and completely replaced it with semantic tag registry system that’s far more elegant than my initial work.

I could not be happier! The new system is indeed fantastic and my PR for sure deserved to be ripped out. No questions about that.

Another example: JRuby library version 4 was awesome. I was in love with it at first sight and began contributing to its development. Then @ccutrer came along and turned it inside out and completely restructured the heck out of it, which eventually became version 5 that is currently in use. I saw that the new changes made a lot of sense and it greatly improved the existing library at the time. I was very happy that it happened.

This doesn’t appear to be the case with the current documentation / gatekeepers.

3 Likes
34

I’ll just add that after reading through this PR, I agree with @jimtng that the “process” is far from ideal and does the opposite of inviting to contribution. Even though the language is polite, the crux of the matter is that the contribution isn’t really evaluated and is rejected because “it changes too much”. That will surely discourage anybody that wants to do a restructuring of something.

I don’t know how to render the documentation and I know nothing about Blocky, so I’m not capable of evaluating if the changes are an actual improvement or not, but I think the discussion should have been about the proposed changes, the ideas/philosophy behind it etc. That way, it could have evolved into something that “everybody” would appreciate. Now, it’s a reminder to the author and other potential would-be authors to not waste their time on anything but spelling mistakes or punctuation instead.

2 Likes
35

The generated preview is still available.

You don’t need to know anything about Blockly to be able to see the difference in the two pages above. You can even change the text with “Lorem ipsum” and not understand a word of it to see the difference

1 Like
36

It seems that the Semantic Model is something you’d like to understand more. Let’s open a separate topic about it, and we can help you understand it. More importantly, figure out how to make it easier for others to understand it in the future, i.e. discover and address any shortcomings in the currently available documentation about it. Note the current documentation that I can find is here: Semantic Model | openHAB (Under “Getting started”)

PS: I think that page belongs in the “Concepts” section, not “Getting Started”. But
 who’s going to make such changes? I’m not going to try that.

1 Like
37

I have looked at it, and your way of organizing it seems like an improvement to me. But, since I don’t know anything about Blocky, I can’t have an opinion about if the right things are presented, emphasized, what priority what is given etc. But, simply as an “ignorant reader” I find “your version” less confusing.

It’s not so important for me to understand more of the semantic model at this time, I think I know most of what I need about it for the time being. I’m using it as an example, exactly because I have the impression that many “struggle” to completely understand how to use it, and because it has caused me some grief in the past.

While it could be a good idea to create a topic where “everybody interested” could collaborate in getting to what is “confusing” and not about it, I’m not sure it’s worth the effort if whatever result that process would lead to won’t get anywhere anyway.

1 Like
38

@jimtng , @Nadahar , @Pedro_Liberal , you have replied to me or otherwise tagged me in this thread but I meant what I said. I’m done here. It’s clear that my presence is not providing anything positive beyond being “discouraging”.

If there’s something in the replies that require my response pm me and I’ll come read your replies and provide responses. Otherwise, you all can have the last word on whatever was the topic of the reply.

I really didn’t want to get involved in another thread like this in the first place and should have listened to my gut instincts. But who knows, maybe something will come of this thread in the end.

4 Likes
39

Oh come on, stop that demanding attitude, please.
What you cite is the blog entry for the OH release.
If you take that together with the release notes, all the info you want is there.
It’s not long. It’s covering what way more users than yourself expect from such a document, a non-condensed, non-technical description of “what’s new”, that is.
But still you expect us to shorten it rather than spend those one or two extra minutes reading the parts you’re not interested in. Really??
BTW the equivalent blog post for 4.3 is right now being prepared and will be released at the same time as OH4.3 and its release notes.
So go read it and don’t demand anything beyond.
We’re not your mom to meet and feed your personal expectations.
That attitude is really upsetting.

It also doesn’t work as a general model, user’s expectations/demands on what and how the docs should be to suit their (and only their personal !) needs differ so widely that no single docs concept can cover them. User interests, views and prior knowledge vary wildly.
We (devs, volunteers) will not waste our time attempting to be the mom for every single one of them, got better things to do.

2 Likes
40

There we have the defensive attitude in full bloom again. First of all, I’ve tried to say that it’s not a very important point, so don’t focus too much on it. Second, this has clearly been presented as a wish, not a demand. Third, I still don’t think you understand what I was trying to explain: I wasn’t talking about shortening the blog post or changing the annoncements etc. I was trying to explain what a “changelog”, that I was wishing for, could look like.

The purpose of a changelog is somewhat different than release notes and accouncements. It’s not there to inform you of “what changed just now”, it’s there so that you can track what changed when, to get an overview.

If you expect everybody to follow what’s happening with OH in “real time”, I’m sorry to disappoint you, but that isn’t likely to happen (some do I’m sure, but not the majority). That’s why it’s very useful to have a changelog to consult when you need to get yourself up-to-date at a later point in time. You also seemed to ignore the fact that not every release is covered by the release notes.

And personally, I won’t remember that I have to go to the forum, or reddit etc, to try to look for announcents and then try to “stitch together” an overview over what happened between point “x” and point “y”. I just do too many different things, so I have to rely on “conventions” for things like changelogs. Sure, I remeber it right now, no problem, but in a year? I’m not so sure.

But this is also all fine. I’m in no way “demanding” a changelog, I was suggesting that it might be helpful since it seemed to me that I wasn’t the only one that didn’t pick up changes. I’ll manage, the “biggest risk” is that I will annoy someone by asking questions that has already been described in some announcement I haven’t found. And, my reference to the “shortening” of the release blog was just to say that the “work” of making a changelog was already being done, all it took was to “extract” the information from the blog. I never meant to insinuate that the blog should change.

1 Like
41

I did, easy. But I think you still don’t understand that that’s right the demanding attitude we (devs and non-devs supporters to answer you) are unwilling to support here.
That’s not “defensiveness”.
That’s protecting our goodwill, valuable time and motivation.

I don’t, we don’t.
But we expect users to be willing to spend at least as much of their time as it takes them to gather and understand the information it’ll take for them to benefit from software that we built for them, for free.

We’re doing the cooking, you eat for free, but it’s not us that you may expect us to serve you the meal the way you want it.
The information is all there, and it’s not at all unorganized or hidden or anything similar legitimately criticizable.

Time for some gratitude.
Your turn, not ours.