Documentation in openhab vs. current Google Assistant features

Hi Folks,

i’ve been struggled with changes in Google assistant (topic: specialcolorlight) - i solved it by searching here and putting the puzzle together.

My concern is, that the documentation about google assistant and it’s features are aligned to an openhab version. But i think this is “wrong”. There are 2 different topics:

  1. Documentation of openhab, what is available with the ui for example
  2. Documentation of Google Assistant features, which are currently LIVE/online.

For example: in the GA Doc of openhab 3.3 (current version) the Light-Group is described as it was months ago (ga=“Light”). In “next”, better openhab 3.4 documentation you see the changes to “specialcolorlight”.

But this doesn’t depend on the openhab version, it depends on the current “installed” version of google assistant in the cloud.

So people which take it serious and really read the documentation will fail, because it doesn’t fit to reality.

In my opinion there’s a need of an documentation and versioning of the Google Assistant Adapter and make this clear in the openhab documentation of Google Assistant. Also explain, that the features not available in the ui (like “specialcolorlight”) can be achieved by changing the meta-data in the “Code”-section of the Meta-Editor in the ui.

Who can decide / do this ? Any other opinions ?

Regards,
Kai

2 Likes

Oh wow. You’re right.
Thank you for sharing :slight_smile:

Edit:
Well actually, now that I think about it, nothing stops you from installing the cloud thinggie locally on your pc, and become independent from myopenhab.org entirely.
And in that situation, knowing what version you have installed, becomes relevant.
So maybe what is missing is a hint, or note, clarifying exactly that - for the on cloud connection, the team responsible for that connection takes care of the update - and maybe a link identifying which version is it running currently??

1 Like

Very valid start of a discussion!

I myself struggle a lot with that situation and I do not understand the relation between what is published on the openHAB documentation for this or the next version.
So it seems that the current “live” documentation of the GA integration repository is only displayed for the
next version. But where does the “stable” one come from??
Maybe there is someone here to explain this.

Also that UI integration is very frustrating. Especially, since the UI is bound to a new openHAB version but an update to the GA integration can happen at any time, which leads to inconsistencies and frustration at the end-user side.
Unsure how to solve this… Holding back any GA integration update for a new openHAB release??

Who will maintain the UI configuration part? So far it was done by someone. I myself do not feel responsible, to be honest. Although I maintain the integration’s code now.

At the end the fun part here is that the GA integration is completely - really completely - independent from whatever openHAB version is running.

EDIT:

Btw. the currently release version of the integration is always published on GitHub. So there is documentation and versioning. Just not displayed within openHAB.

1 Like

Yep, I check it once in a while, and I’ve left some requirements as well.
But it’s like you say, due to the nature of the binding, it falls on a no man’s land I believe.

Hi all,

I am on mobile and not sure about the GA codebase in detail, but generally we have a special build solution exactly for this usecase which we use definitely for openhabian and Alexa.

The corresponding maintainers of those solutions can force an active push of new doc content, when they release a new version apart from openHAB itself.
This active push will trigger an update pull request in the docs codebase, which then will be integrated in the “stable” documentation.

I am not sure if we have it enabled finally for Google assistant, but I remember that I have proposed changes to the GitHub repository at least to prepare this.

I will have a detailed look later, when I have a normal screen to work with.

1 Like

Just to elaborate a little on @Confectrician’s answer.

In general, the “stable” version of the docs comes from the state of the docs at the last release. That means they are the docs for OH 3.3 (in this case). However, some parts of OH advance independently and, as @Confectrician indicates, there is a mechanism to support “back porting” changes to the “stable” docs as necessary.

Someone needs to do it or else we may as well not have GA integration at all. Having wrong UIs is worse than having none at all. Could you at least file an issue so the UI maintainers know when a change has occurred? If not, I’ll file an issue to remove GA from the UI entirely. If it’s not kept up to date it’s worse than not being there at all.

2 Likes

Thanks for sharing your thoughts.

I am happy to support keeping the UI up to date, but this still does not solve the issue of being bound to a release to have new changes included. Same for the docs.

So syncing the integrations releases with the openHAB ones seems to be the only option for now…

From my POV the code config option is an okayish way to set up things, while I do understand that using select boxes and switches is more user-friendly.

1 Like

That sounds quite interesting. Please share more insights when possible :slightly_smiling_face::slightly_smiling_face:

1 Like

There is actually a workflow in place to sync up the documentation. I opened the PR below to add that support.

Update: I forgot to mention that @Confectrician should be able to manually trigger the job in the openhab-docs repository so that a new release is not necessary just to sync up the documentation.

2 Likes

True, and we could probably live with a little bit of a disconnect if we cover it in the docs. For example, adding a short section saying something like:

If you do not see an option documented here in MainUI, it means you have a version of OH that has not yet been updated to reflect the latest changes. In that case click on the code tab in MainUI and enter the setting manually.

Then show a screen shot example or something.

Then we can do our usual RTFM when problems arise on the forum.

I can say I personally was really confused when I was helping someone with GA support and they had “Light” but not “SpecialColorLight” as an option. I looked in the docs and saw that the 3.3 docs still said “Light” and the user was using 3.3 and MainUI was only showing “Light” and was confused when it didn’t work. Eventually we figured out manually entering “SpecialColorLight” in the code tab to get it to work but it took some time. With the above in the docs coupled with the ability to push updates back to “stable” I think it’d be more supportable for us.

Question, is there an announcement thread where updates and breaking changes are announced?

1 Like

As I lack permissions for the actual announcements area, I recently just used this: openHAB Google Assistant: A new version is released - #32 by rpwong

That’s cool. I just wanted to make sure I’m subscribed to something so I can keep up with changes and save some time by anticipating problems coming down the line.

Thanks!

Yep you are right, but this was completely out of my focus to be honest.
I am not using any voice assistant and the other workflows/actions are working so flawless. :sweat_smile:

Anyway we are on a good path with actively forcing a docs update.
The repo maintainers know best when changes regarding their docs should be transferred into the website and they also have to ability to finetune everything before pushign “the button”. :slight_smile:

Agreed. My suggestion was for the first run to avoid creating a new release since the documentation is currently out of sync. The PR above will ensure that subsequent releases will trigger the sync job.

1 Like

As it seems that the token is provided, I will merge the PR soon and do a small maintenance release to test the new trigger.

Additionally, I spent some minutes providing a PR for updating the metadata in the webUI: Update GA metadata to current state by michikrug · Pull Request #1539 · openhab/openhab-webui · GitHub

4 Likes

Hi guys,
I’m already happy that this discussion will lead to a change and to get out of this confusion.
For this i have a wish: Can you somehow mark the GA-Docs with a version and a date since when these version is online (also within the openhab docs) ?
By that a user has a chance to see what is different to his installation and since when. If i configure my lights - i won’t change them any 2 weeks. WIth this i can see, “oh, there’s a specialcolorlight for groups since 3 months - i configured my lights a half a year ago, i have to change it”.

With a version and a date it’s possible to comprehend any changes and the date of it. And a link to the git-repo will be nice, so a “more technical user” could check the history.

Thanks.

1 Like

That was hinted some posts ago indeed, and it would be super helpful.
My comment doesn’t help much but I’d also love that, otherwise we lose a bit of transparency.

1 Like

This is a good idea for sure.

As it does affect more repositories than the ga integration, we should probably implement this from the docs/website side and provide some kind of “meta box” to show this information, when it is provided.

We could use some kind of build script automation to provide the needed data in the docs frontmatter section. (For the intersted user: This is a block filled with meta informations in a markdown file, like we use for documentation).

@michikrug

Maybe Generate & update markdown content · Actions · GitHub Marketplace · GitHub could be used to add the current release and it’s publish date, when updating the docs.

3 Likes

To fulfill some of the requirements or ideas stated here, I added the following:

This block is currently added manually. So far I did not yet find a useful application of the mentioned GH action to automate this.

[EDIT] Oh, and there is a TOC now :smiley:

7 Likes

I’m enjoying this thread very much :slight_smile: thank you for keeping us up to date!