For some bindings, a restart of the binding and/or OH itself is required to pick up changes to .things files.
Yep, and if you want to change it you have to change it in the .things file if that’s where it’s defined. It’s either or, not both. You can’t modify a Thing in the UI that’s defined in a .things file and you cannot modify a Thing in a .things file that’s defined in the UI.
In part that’s because the UI is able to be more self documenting. You don’t need to know each and every possible property on an MQTT Channel, they are all just presented to you with a brief description of each field in the UI.
KNX and modbus are to exceptions. Because of their complexity, I believe the general recommendation is to avoid the UI for these bindings.
But ultimately, the focus, detail, and approach each binding author takes to document their individual binding is up to them. Some choose to only show .things syntax while others choose only to show UI and still others show both.
I think the best that can be done is to file issues and submit improvements to the add-on docs where a deficiency is found.
That is to some extent legacy. But there is a rewrite of the way the rules are presented which will not favor any rules language over others.
To the best of my knowledge, there’s no generic explanation of things and items syntax as it has not been recommended to use that ever since OH2 came out.
It’s there. But for Things in particular, knowing the generic syntax is only part of the problem. The user also needs to know all the properties and valid values supported by the binding and not all binding authors provide everything needed in their docs.
The Items reference is pretty complete though, really only lacking a good section on metadata.
But defining them in the UI is not even addressed in the reference docs yet and I think that can lead to confusion.
I think it’s important to understand what the different sections of the documentation are for.
- Concepts: intended to provide definitions and explanations for core openHAB concepts
- Getting Started: to show how to implement a config, demonstrate the core openHAB concepts and show how they all work together
- Configuration Guide: these are reference docs; these need to be used like you’d use a dictionary or an encyclopedia. You look stuff up in them, not read them from beginning to end.
- Add-on docs: should provide everything you need to know to install, configure and use the add-on.
So yes, of course the Configuration Guide is always going to be text config heavy. You don’t need as much reference material in the UI since it’s mostly self apparent. But much of that reference material is going to be the same. Rules DSL syntax is mostly the same whether it’s in the UI or in .rules files. Things and Items syntax is mostly irrelevant in the UI. MainUI Widgets syntax is not well supported in text files at all.
But that doesn’t mean improvements are not welcome and needed. A complete overhaul of the rules is in work. This will include a rewrite of the Actions. All examples include Rules DSL, Jython, JS Scripting, and JRuby. I’m still thinking about how to do Blockly. See Rework Rules Documentation · Issue #1855 · openhab/openhab-docs · GitHub if you want to pitch in and help.