I’ve been holding off on some of this and stopped my Next Gen threads for now largely because it’s a bit of a moving target. Some open questions/things in work that I think need to be completed before we go too far down this path:
- there are a few important bugs that are in process of being fixed, the big one that comes to mind being the broken System started triggers
- the separate helper libraries are under the process of becoming merged into one central library
- I believe the plan is to distribute the helper libraries so they can just be used, no extra download and update necessary
- similarly, I believe the plan is to distribute the Jython jar file (I don’t know what Groovy needs) so all three languages are equal full class citizens in the OH ecosystem
- while the underlying engine is the same, creation and management of Rules will look and therefore require very different documentation for GUI created Rules and text created Rules.
Hopefully Scott can provide some insight into whether I’m correct in these statements and a timeline: already done, likely part of 2.5 release, definitely part of 2.5 release, not until 3.0 or beyond.
For example, if the libraries and needed jar files get installed as part of the Experimental Rules Engine package or separately install-able as it’s own OSGI bundle (or whatever) then the Installation section of the docs becomes moot. Similarly, if we distribute the helper libraries (in which case they cease being helper libraries and become “the way to do things”) the docs could look pretty different as we won’t have to document a whole lot of stuff beyond “use this function in the library”.
Anyway, let’s just assume we would be documenting what exists right now.
It might be helpful to include a little bit of a generic theory of operation section explaining how OH overall works. We would include information like how OH is event based, how events flow to/from Rules, common gotchas that will be true no matter the language (e.g. sendCommand won’t necessarily change the state of the Item immediately), stuff like that. Given the questions we see here in the forum, some of these basic fundamentals about how it all works are missing. This may be what you intended by “how does it work” but I want to state it outright in case it wasn’t.
I also think we need to have two types of documentation. We need reference docs, which is frankly all we have now with Rules DSL. But what is missing and what I think we will need is some sort of tutorial that gradually introduces Rules programming concepts to the users. We should note have to reproduce the underlying language’s basics though links to tutorials and reference docs will be needed. But something that looks a lot like your Time of Day translation tutorial where we start very simple (log out something to show it works) and gradually build up a Rule with links and help to teach the users how to use the reference documentation might be useful. As we build up the Rule(s) in the tutorial we introduce important concepts like the different rule triggers, useful Actions, working with Items and Groups, timers, etc. We don’t need to put everything in the tutorial, that’s what the reference docs is for. But we want to give the users, particularly non-programming users, a hands on path they can follow and do to understand important Rules concepts and get them used to looking for answers in the reference guides.
If we can hold the user’s hand a bit we might have a better first experience for some users (some won’t read the docs no matter how good they are). It’s just a thought.
To reiterate in bullet form, with a few more ideas added:
- overall theory of operation for Rules in OH
- reference docs separate from tutorial
- per language design patterns? Some I imagine would be universal as they have to deal with how OH works
- when it becomes available, where and how to find and use rule templates (maybe that will eliminate the need for design pattern docs)
I strongly suspect that the overall way that users create their Rules is going to be very different once we have Rule Templates and the GUI Rules builder. Many/most average users will click together their Rules, sometimes even very complicated Rules using the GUI and importing and using Rule Templates. Advanced users like us will become Rule Template writers and there will become an ecosystem akin to bindings for Rules Templates as well. If this does happen, it will only be the very technically advanced users who will be writing .py/.js files by hand. At that point the reference guide will largely become a guide for developers. We are a long way from that but it’s where I can see this going.
I think almost all we need in terms of reference information, at least for Jython and perhaps for JavaScript are available in various places. We should be able to consolidate that into the official docs and that all by itself would be an improvement. The step by step tutorials need to be written, but you’ve already a big jump start on that.
I feel like I’m rambling so I’ll stop here.
, but have yet to merge the Jython helper library portion, as it will be included with an upgrade to support the 2.5 and the ESH reintegration. However, the StartupTrigger will only be available with helper libraries, until an official one is written.
! Here’s an example of what you can get from the javax.script.ScriptEngineFactories when JS, Groovy and Jython are present…
