Open rkoshak opened 2 years ago
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.
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.
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.
I'll spin up a branch.
@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.
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.
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
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
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
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
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.
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
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
Blockly --> As currently written, just need to move the page under Rules
@rkoshak What do you mean by that?
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.
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
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
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
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.
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" 😄
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.
Looks like it'll fit
This issue has been mentioned on openHAB Community. There might be relevant details there:
I have lately added collapsable levels like so - which might help?
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!
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.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.