Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework Rules Documentation #1855

Open
rkoshak opened this issue Jul 6, 2022 · 26 comments
Open

Rework Rules Documentation #1855

rkoshak opened this issue Jul 6, 2022 · 26 comments
Milestone

Comments

@rkoshak
Copy link
Contributor

rkoshak commented Jul 6, 2022

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
Copy link
Contributor

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
Copy link
Contributor Author

rkoshak commented Jul 8, 2022

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
Copy link
Contributor

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
Copy link
Contributor Author

rkoshak commented Jul 8, 2022

I'll spin up a branch.

@florian-h05
Copy link
Contributor

@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
Copy link
Contributor Author

rkoshak commented Jul 12, 2022

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.

florian-h05 added a commit to florian-h05/openhab-docs that referenced this issue Jul 12, 2022
This covers 1 and 1a of the table at
openhab#1855.

Signed-off-by: Florian Hotze <[email protected]>
@Confectrician Confectrician added this to the 3.4 milestone Sep 10, 2022
@openhab-bot
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Collaborator

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

Confectrician added a commit that referenced this issue Nov 18, 2022
* Getting started

Signed-off-by: Richard Koshak <[email protected]>

* [Rules] Add Rules Concepts page

This covers 1 and 1a of the table at
#1855.

Signed-off-by: Florian Hotze <[email protected]>

* Address @rkoshak 's review

Signed-off-by: Florian Hotze <[email protected]>

* Address @rkoshak 's review

Signed-off-by: Florian Hotze <[email protected]>

* Address @rkoshak 's review

Signed-off-by: Florian Hotze <[email protected]>

* [Rules] Add concept docs for triggers

Signed-off-by: Florian Hotze <[email protected]>

* [Rules] Add concepts docs for conditions

Signed-off-by: Florian Hotze <[email protected]>

* Address @rkoshak 's review for triggers

Signed-off-by: Florian Hotze <[email protected]>

* Address @rkoshak 's review for conditions

Signed-off-by: Florian Hotze <[email protected]>

* Address @rkoshak 's review

Signed-off-by: Florian Hotze <[email protected]>

* [rules] Add remaining sections of concepts page

Signed-off-by: Florian Hotze <[email protected]>

* Add note about "Scenes" to rules concepts

Signed-off-by: Florian Hotze <[email protected]>

* [Rules Concepts] Add Scripts and Script Actions sections

Signed-off-by: Florian Hotze <[email protected]>

* [Rule Concepts] Add Available Values, Rule Templates & Helper Libraries sections

Signed-off-by: Florian Hotze <[email protected]>

* [Rules Concepts] Add comprehensive examples with JS Scripting code snippets

Signed-off-by: Florian Hotze <[email protected]>

* [Rules Concepts] Add DSL code to comprehensive examples

Signed-off-by: Florian Hotze <[email protected]>

* [Rules Concepts] Add UI rule code to comprehensive examples

Signed-off-by: Florian Hotze <[email protected]>

* [Rules Concepts] Add UI rule screenshots to examples

Signed-off-by: Florian Hotze <[email protected]>

* Address @rkoshak 's review

Signed-off-by: Florian Hotze <[email protected]>

* [Rules Concepts] Add JRuby examples from @rkoshak

Signed-off-by: Florian Hotze <[email protected]>

* [Rules Concepts] Link to the JRuby Scripting addon

Signed-off-by: Florian Hotze <[email protected]>

* Update docs-sidebar.js

Added the new rules concepts page to the sidebar.

Signed-off-by: Rich Koshak <[email protected]>

* Addressing MD Linting

Signed-off-by: Richard Koshak <[email protected]>

* Removing files we are not ready to push to upstream

Signed-off-by: Richard Koshak <[email protected]>

* Removing files we are not ready to push to upstream

Signed-off-by: Richard Koshak <[email protected]>

* Removing files we are not yet ready to push upstream

Signed-off-by: Richard Koshak <[email protected]>

* Deleting files not ready to push to upstream

Signed-off-by: Richard Koshak <[email protected]>

* Removing files not ready to push to upstream

Signed-off-by: Richard Koshak <[email protected]>

* Removing files not ready to push to upstream

* Removing files not ready to push to upstream

Signed-off-by: Richard Koshak <[email protected]>

* Moved new rules concepts page to the concepts folder.

Signed-off-by: Richard Koshak <[email protected]>

* Fixed paths to images

Signed-off-by: Richard Koshak <[email protected]>

* Attempting to fix tabs for examples

Signed-off-by: Richard Koshak <[email protected]>

* Fixing tabs for last two examples, cleaning for consistency

Signed-off-by: Richard Koshak <[email protected]>

* Fix old gh pages syntax

Signed-off-by: Jerome Luckenbach <[email protected]>

Signed-off-by: Richard Koshak <[email protected]>
Signed-off-by: Florian Hotze <[email protected]>
Signed-off-by: Rich Koshak <[email protected]>
Signed-off-by: Jerome Luckenbach <[email protected]>
Co-authored-by: Florian Hotze <[email protected]>
Co-authored-by: Jerome Luckenbach <[email protected]>
@Confectrician Confectrician pinned this issue Nov 26, 2022
@openhab-bot
Copy link
Collaborator

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
Copy link
Contributor Author

rkoshak commented Dec 16, 2022

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
Copy link
Contributor

@openhab-bot
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Contributor

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

@rkoshak What do you mean by that?

@rkoshak
Copy link
Contributor Author

rkoshak commented Mar 12, 2023

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
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Contributor

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
Copy link
Contributor Author

rkoshak commented Oct 2, 2023

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
Copy link
Contributor

jimtng commented Oct 2, 2023

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
Copy link
Contributor Author

rkoshak commented Oct 3, 2023

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
Copy link
Contributor

jimtng commented Oct 4, 2023

Looks like it'll fit

image

@openhab-bot
Copy link
Collaborator

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
Copy link
Contributor

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

image

@rkoshak
Copy link
Contributor Author

rkoshak commented Feb 12, 2024

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

7 participants