Documentation on Automation / Scripting

[jimtng]

It seems to me that the current documentation at https://www.openhab.org/docs/ doesn't really explain that well, the wonderful options we have for automation and scripting.

• I think the JSR223 document, as it is now, belongs more under the Developers Guide section.
• The more 'end user' page explaining about scripting should mention and link to the automation addons. At the very least, a callout or a footnote within the Rules DSL page, similar to what's being done with Blockly.
• Furthermore, JSScripting, Jython and JRuby all have helper libraries that make scripting with them for the end users far easier than the JSR223 page is portraying. This should probably be pointed out in the interest of making it easier for a new openhab user to quickly get an idea about their options. As it is now, you'd have to be 'in the know' or dig around to know, as it is not immediately apparent.

[rkoshak]

I think the JSR223 document, as it is now, belongs more under the Developers Guide section.

No, despite looking the way it is and how it's written, it doesn't belong in the Developer's section because it actually does show end users what is available in their rules when using one of the JSR223 languages. I don't know where it's best placed but in the Development section isn't where it belongs, at least not yet.

I fully expect it to become deprecated at some point anyway since I think only ECMAScript 5.1 and Jython use it. The rest of the automation add-ons provide their own helper libraries that hide all of that detail. Maybe it would make sense to move it to the development section when ECMAScript 5.1 and Jython completely goes away. For ECMAScript 5.1 that will be relatively soon (within a year or two I expect, as soon as we move to Java 17).

Furthermore, JSScripting, Jython and JRuby all have helper libraries that make scripting with them for the end users far easier than the JSR223 page is portraying. This should probably be pointed out in the interest of making it easier for a new openhab user to quickly get an idea about their options. As it is now, you'd have to be 'in the know' or dig around to know, as it is not immediately apparent.

While I don't disagree, it doesn't feel like it's the core documentation's job to document what individual add-ons do or do not provide. How would we keep up? Because the Jython and ECMASCript 5.1 Helper Library was never actually made a part of the openHAB project, documenting it too seems a bit out of place since, for all intents and purposes it's a third party package.

The helper libraries for individual add-ons (e.g. jRuby, JS Scripting) should be thoroughly documented in the individual add-on's docs for sure. I know that's the case for JS Scripting at least.

I completely agree that the rules docs need a complete overhaul. But a lot is also in flux right now with ECMAScript 5.1 definitely going away sometime soon, Jython likely to go away sometime soon since the upstream doesn't seem to be well maintained any more. There's even rumblings that the upstream for Xtend (upon which Rules DSL is built) might be abandoned by the Xtext folks. So right now OH ships with default languages whose future are not certain.

I fear spending too much time making changes that ultimately will not be relevant for long.

As I've been working on the Getting Started Tutorial, which I need to find time to get back to so I can get it submitted as a PR, I've considered the following as potential next steps.

• Have a generic Rules page that discusses the concepts of rules (triggers, actions, conditions, implicit variables, etc.). The stuff that is common no matter how you are writing your rules.
• That generic documentation would necessarily include examples. The examples should be limited to what OH ships with by default, meaning:
  • UI Only
  • Rules DSL (in the UI and .rules files)
  • Blockly
  • ECMAScript 5.1 without the Helper Library (in the UI and .js files)
• The generic documentation would link to the automation add-ons list as well has providing direct links to the Rules DSL reference page, Blockly reference page, and the JSR223 page for JavaScript.

So the basic flow would be to look at the generic docs for general rules concepts and then click through to the specific page that provides the detailed reference for the language you are using. Each automation add-on provider would be responsible for providing information about their respective helper library and any other relevant reference documentation.

It doesn't make sense to me to put a whole lot of effort into ECMAScript 5.1 docs since we know for sure it's going away, which is why I recommend just pointing to the JSR223 docs for it for now and then when it goes away move the JSR223 docs to the development section.

It might make sense to not even reference ECMAScript 5.1 in these docs at all and instead jump straight to the JS Scripting for the examples in the generic docs. Right now Blockly renders to ECMAScript 5.1. When that goes away it will be modified to render to JS Scripting. At that time, JS Scripting will need to become something installed by default, similar to rrd4j so it wouldn't be inappropriate to reference it in the generic docs.

Those are just my thoughts. I'm stretched pretty thin right now trying to finish the Getting Started Tutorial and adding features to the JS Scripting helper library so that when the time comes to move Blockly to it it won't be too hard to do, and add some nice features while I'm at it.

That's my two cents worth at least.

[Confectrician]

So for a first short response:

Configuration is (at least currently) the proper area for the JSR223 Article.
I am not sure where the duscussion is currently, but i think we had one about a proper "rules" area in the docs already.

The paragraph above goes into the right direction for me.

We should

• cover automating the smarthome as a topic in general
• descibe the several possibilities in general
• point/link to specialized articles like the blockly one currently is

Pointing and linking is also the only way for external libraries, as long as they don't integrate into any repository we have under our control.
I am stricly against bringing foreign docs into our website.
If one integration offers scripting via binding like openhab-js does for example, we already fetch their docs automatically.

And we should stay with this workfow.
-> Keep the docs aside the code. This way is probably the best to make sure that codebase and doc are in sync.

As it is now, you'd have to be 'in the know' or dig around to know, as it is not immediately apparent.

I perfectly understand and respect the thoughts behind this, but the honest questions we would have to ask are:

• Who does the maintenance of such information?
• When is a library popular/known enough to be listed?
• Is the community forum the only place to look for new libraries?