Rework Rules Documentation

[rkoshak]

The rules documentation is in sore need of reworking. All of the basic rule concepts documentation is embedded in the Rules DSL reference docs. The JSR223 page is too prominent and incomplete. Some of the add-on rules languages do not have much documentation at all.

I think the Getting Started Tutorial makes an OK first crack at explaining rules and rules concepts but as a tutorial, it's incomplete.

I envision a set up more like the UI section of the docs and propose an outline along these lines. Everything below would be under a Rules heading in the sidebar.

Done	Section	Title	Contents	Notes
✅	1	Rules Concepts	Explain how rules work, parts of a rule, etc	Language independent, expand on the Getting Started Page
✅	1a	What are rules	Even driven, made up of parts, other rules concepts
✅	1b	Triggers	Explain triggers and list all the triggers	Most of this content can come from the Rules DSL page
✅	1c	Conditions	What are they, where are they supported, etc.	New content
✅	1d	Script Actions	What are they, where are they supported, etc.	Expand on the content in the Getting Started Tutorial
✅	1e	Implicit Variables	What gets passed to the rule when it's triggered	Probably needs a new name
✅	1f	Rule Templates	Where to find them, how to install and configure them	Expand on content in the Getting Started Tutorial
✅	1g	Helper Libraries	What are they, where to find them
✅	1h	Comprehensive Examples	Use tabs and show most of the popular languages	Includes UI and text based, emphasis on use of helper libraries
[ ]	2	Rule Actions	List built in rule actions, describe binding actions	Most of the content already exists, may want to rework order, move persistence actions to here, move the cloud notifications to the add-on's docs? Include examples in multiple languages
[ ]	2a	Event Bus
[ ]	2b	Audio & Voice
[ ]	2c	Logging
[ ]	2d	Exec
[ ]	2e	HTTP
[ ]	2f	Semantics
[ ]	2g	Timers
[ ]	2h	Thing Status
[ ]	2i	openHAB Subsystem
[ ]	2j	Ephemeris
[ ]	2k	Persistence		Move the content from the Persistence page to here
[ ]	2l	Binding Actions	Where do they come from, how to call them
[ ]	3	UI Rules	How to create rules in the UI	Expand on the content in the Getting Started Tutorial, reference section 1
[ ]	4	Text Rules	Generic concepts, where they are placed, loaded, etc.	Most of the specifics will point to the individual language references, provide comprehensive examples
[ ]	5	Blockly		As currently written, just need to move the page under Rules
[ ]	6	Rules DSL	Reference docs	Move the generic concepts to 1, focus primarily on language reference
[ ]	7	Raw API	Reference docs	The current JSR223 page with additions for stuff like the event Object unless that's covered in 1e
[ ]	8	Rule Templates	How to write and publish a rule template

The overall approach and intent should be to consolidate the generic and move the specific to their own page. One should not have to learn Rules DSL to understand the basics of a rule. We should not favor any one language or approach in the examples (I like having tabbed examples like on the JSR223 page).

With the addition of all these new pages we may need to consider whether it makes sense to keep the sidebar flat like it is now. This is going to add half a dozen new pages to the sidebar.

Refinements and other ideas are welcome. This is probably bigger than one person if we want to have it completed in anything like a reasonable amount of time. So if you want to contribute let's use this issue to coordinate.

[florian-h05]

Your approach looks really good to me, it seems to be ver detailed and structured!

I am willing to contribute parts of the docs, but I currently have a few other things with higher priority in my to do list.

[rkoshak]

Yes, availability is my limiting factor too. I might get a PR started on my fork linked to this issue just so we have a single PR we can all contribute to, unless @Confectrician you would rather see the PRs for this broken up into smaller chunks to make it easier to review.

I'm also open to an alternative organization or other ideas for how to present rules info in a consistent and maintainable manner.

[florian-h05]

I do not know what @Confectrician prefers, but I as well think that it would be better to review and also better to preview if we have one single PR.

I would like to have a branch for this on your fork @rkoshak and a PR from your fork (even when it is fat away from finished, but we then have previews on netlify).
Then everybody who wants to contribute can work on a part and then open a PR to your fork.

[rkoshak]

I'll spin up a branch.

[florian-h05]

@rkoshak Are you currently working on anything?
I would like to start with 1 - Rules Concepts, but don't want to waste my time by doing something somebody is already doing.

[rkoshak]

I haven't started on anything yet so have at it. My overall thoughts on that page is to use the existing Concepts pages in the docs as a template for how much detail to include. We want to add enough that users know what rules are for and the parts of a rule and such but not necessarily how to write them.

Keep in the back of your mind whether or not it makes sense to have that page as a part of the Concepts section instead of the Rules section. The more I think about it, the more I think that it belongs there (along with a new concepts page for Persistence).

The Concepts section is where one learns the "terms of art" about OH and the Configuration section is where one learns how to apply them.

That's my current thinking anyway.

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/scenes-openhab-vs-home-assistant-in-2022/138782/21

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/suggestions-for-documentation-introduction-section/140328/5

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/configuration-gui-vs-files-questions/140711/17

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/best-way-for-me-to-write-rules-in-openhab-3/139880/10

[rkoshak]

Note: We should add an intro page to the new Rules Section under which all the pages after 1 will be placed. Add a table listing each language perhaps with number of attributes so users can easily compare and contrast and choose which they want to use.

We have to decide if we want to also include external like Node Red and HABApp.

[florian-h05]

Reference https://community.openhab.org/t/best-way-for-me-to-write-rules-in-openhab-3/139880/12.

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-4-0-wishlist/142388/52

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-4-0-wishlist/142388/221

[stefan-hoehn]

Blockly --> As currently written, just need to move the page under Rules

@rkoshak What do you mean by that?

[rkoshak]

This Issue is to consolidate all the rules reference docs under a single heading similar to how UIs has its own section with pages for sitemaps, MainUI, etc. Blocky's reference would move to under that heading too. The current Rules page would be renamed Rules DSL and updated and both the JSR223 and Actions pages would move under that heading too, with changes.

The intent is for the use to refer to the rules page under Concepts for genetic understanding of the parts of a rule and what they do and the pages under the new Rules sections are references to specific rules languages.

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/openhab-marketing-is-lacking/149280/75

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/call-to-action-volunteers-for-openhab-marketing/149618/169

[MyRaceData]

Rich, I saw your request for help with the docs on the forum and I'd be willing to help. Is there any one thing in particular you would like me to start on? I am user Andrew_Rowe on the forum

[rkoshak]

So far we have the rules page under concepts pretty well established. Please review that to see what's documented there (so we don't duplicate docs in multiple places) and to see the overall conventions we've been using.

After that what we need are at the stage where we need to start restructuring. The best way to do that I'm not sure. I'm thinking we follow the precedent of the UIs and create a new "Automation" section (I go back and forth whether it's better to call it that or "Rules", today I'm leaning towards "Automation" but tomorrow 🤷 ).

Under that we will have sections 2-8 as described in the above outline. My initial thought was each major section would be it's own page, but I can also see combining some of them onto one. The order shown above is not set in stone.

Given that, I'd say take a section above and run with it. Create a branch on your fork and I can help with the reworking of the sidebar if you don't know how to. Most of the content is already there, we just need to rework them for OH 4 and include UI, Blockly, and at least JS Scripting, jRuby, and Rules DSL examples where ever we have examples.

[jimtng]

So far we have the rules page under concepts pretty well established. Please review that to see what's documented there

Where is it exactly right now?
I think I found it. It's here, right? https://next.openhab.org/docs/concepts/rules.html

I'm thinking we follow the precedent of the UIs and create a new "Automation" section (I go back and forth whether it's better to call it that or "Rules", today I'm leaning towards "Automation" but tomorrow 🤷 ).

+1 for "Automation"

Or to cover both cases: "Rules & Automation" 😄

[rkoshak]

I think I found it. It's here, right? https://next.openhab.org/docs/concepts/rules.html

Yes, though this was completed before OH 4 release so you don't need to go to next. It's there for the 4.0 version of the docs too.

All the generic "this is what a rule is and the parts of the rule" stuff is covered there along with some simple but comprehensive examples. What's left is to create the reference docs for details.

I expect the Actions section to get longer and the existing Rules DSL docs to potentially get shorter.

I've also been wondering if we should have a separate page for event. Even I often struggle to figure out where to look to figure out what should/should not be in event sometimes. I have to do lots of trial and error.

Or to cover both cases: "Rules & Automation" 😄

That's probably too long for the size of the sidebar menu.

[jimtng]

Looks like it'll fit

[openhab-bot]

This issue has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/item-editor/153739/41

[stefan-hoehn]

I have lately added collapsable levels like so - which might help?

[rkoshak]

I have lately added collapsable levels like so - which might help?

Absolutely.

This is still really high on my list of things to do but it takes a lot more time I can string together into single sittings and my attention is required in too many directions these days. Still looking for volunteers but plan on doing it myself when I can.

But I think collapsable levels support is huge!