Organizing/ structuring rule sets and rules

[toggledbits]

Everyone:

The quality of questions is a common complaint among those of us that provide "support" for things that we build and offer. As evidence of that, I'll direct you to this post over on the Home Assistant community, which apparently itself was inspired by a similar post in the OpenHAB community.

It opens by explaining the obvious: they are volunteers (as am I), the ratio of supported to supporters is high (i.e. there are far more people asking for help than people providing it), everyone's time is valuable, and it's actually disrespectful of people's time to not put up front effort into your questions and structure them in a way that speeds the resolution process along. The common sense of this should be obvious: if you have a problem or question for which you need a fast answer or solution, should you not then give as much information as possible so that the first reply could be the answer, rather than being only the first of what becomes a back-and-forth exchange that could take hours or days to conclude?

So, I am shamelessly plagiarizing the Home Assistant post for my guidelines here, as it is a good summary of both the ubiquitous problem contributors face in these environments, and what is generally needed to make things more manageable and agreeable. I will say, this is a great summary, and it should be applied everywhere you post, not just here. I'm sure everyone here and everywhere reading your posts, not just the contributors, will appreciate it.

Here we go...

Language

I'm opening with this because the Hass post opens with it, but it hasn't been an issue here yet, so simply for the sake of completeness: support here is given in English. Please make your posts in English, if you can. If you can't, please make your post in your preferred language, but start it with a request to the group for a translation; maybe someone can/will help. We'll try web-based translators, too, of course, but technical language is rarely their strong point. This is one of many areas where community help really makes the experience for everyone.

Try Search First

As the product matures and the community becomes increasingly adept with it, it’s increasingly likely that your question has been asked and answered already. If you search the forum, you may find an answer and save yourself a lot of time. It may not be a perfect answer to your question, but it could get you close enough to start.

The forum search here has a tendency to default to "Titles" (as in, search only in post titles), which is a bit restrictive, so remember to expand your search to "Posts," but from there, hopefully, you'll find something useful.

Try to search only for what is the core of your question - the error message text/keywords (without your specific data), component or add-on name, the operation you want to perform, etc.

Try the Documentation

Every version of Reactor has a "Manual" link in the UI's left navigation that will take you to the locally-installed, version-specific documentation. There is also an online version here, but it may document changes and new things that were not available in the version you are using, so be careful there.

Be Up To Date

Before reporting an issue, be on the latest release. If you are not on the latest release, upgrade to it and try again before posting. If you post and are on an earlier release, it's almost guaranteed that the first thing you'll be instructed to do is upgrade to the latest release.

New Topic Guidelines

If you haven't found anything in Search or Documentation, then make a new topic, following these guidelines:

If a search or your casual reading brings you to a topic/post is somehow similar to, but not exactly, your question, it's better to start a new topic and link to the similar in your introduction than it is to post a reply on the topic you found. This is especially true if the topic you found has gone stale and hasn't had a reply in months or years.

A good opening (head) post a new topic will have most, if not all, of the following:

• A concise title;
• Details of runtime environment (Reactor version, platform info);
• If your question is related to a hub/controller, the type of controller and its running software or firmware version information;
• A complete description of your objective;
• A description of your approach/solution/implementation so far (what you did, how it's intended to work), and what isn't meeting expectations;
• Show the work.

Let's look at the details of that:

Title. Having a good topic title is essential. It should summarize your post so that without even opening it people can have a good idea of what it’s about. A good title generally:

• Includes the unique part of the error you’re getting (redact specifics of your system, e.g. device IDs);
• Contains the integration name, condition or action type, etc.;
• Describes the thing you’re having an issue with;
• Is emotionless.

Examples:

• Good: Action runs before delay action completes
• Bad: Timer not working
• Ugly: Problem/Need help
• Good: Hubitat - Not able to perform dimming.set on Zooz switch
• Bad: Can't control Zooz switch
• Ugly: Switch problem

If you’re having a problem writing a good topic title, leave it for last — once you’ve written the whole question, it might be easier to write a summary title for it.

Describe Your Runtime Environment. It doesn't matter if you did it on a post last week, yesterday, or two minutes ago, every post should include a description of your environment, because I don't keep your system configuration in my head, and future readers will need to know. There are too many people and too many details for me to remember those things, anyway. So each post should include:

• What version of Reactor you are using (upper-right corner of UI);
• What OS your Reactor is running on (Ubuntu, Windows, Synology DSM, Raspbian, etc.);
• How you installed/run Reactor: bare metal, Docker, etc.;
• Specifics of any hubs and devices involved (manufacturer, model, software/firmware versionetc.) in the issue.

Example: Reactor 21308-afecb92a; docker on Synology; Hubitat or Ver 21262; Raspian bare-metal (RPi4); Vera 7.32; Fibaro FGZ-712

Describe the objective, not the problem with your implementation. It’s all too easy to fall into the trap of the XY Problem. If you describe your objective first, then others can understand what you’re trying to achieve. Remember, your objective is not a description of how you're implementing your solution, it's a description of the problem you are trying to solve with your implementation.

• Good: I am trying to get an outdoor light to be on from the day after Thanksgiving through the end of the year.
• Bad: I'm trying to figure out a condition to detect the day after the fourth Thursday in a month.
• Ugly: The date condition in the screen shot below doesn't work.
• Approaching Crime: I tried X and it didn't work (and that's the entire substance of the post).

The first description is (much) better not just because it's concise about timing, but also complete: it lays out the entire problem, not just the one part of it that's giving you trouble right now. Often, good solutions will vary based on the full understanding of the objective (imagine trying to help someone solve the problem of getting fresh air into a large space if they didn't bother to tell you they were building a submarine). It is confusing to other readers and frustrating to helpers when you focus on one step, and when that's resolved, you then add "OK, and now it also needs to...". In the worst case, it can make the entire discussion prior useless.

Show Your Work. Think mathematics class in school: you got no credit for having the right answer if you didn't show how you got there. Worse, if you're sure you have the method correct but you got the wrong answer, nobody could see anything to help you figure out why, including yourself. A big part of the completeness of your response is showing what you've done to try to address it:

• Describe (and show) what you’ve tried, and what the problems were;
• Almost every question about rules or reactions needs to have accompanying screen shot(s) showing the rules and/or reactions you've built; if your description says "I made a rule/reaction that does X", you need to show it; if you say "I tried to do X but it didn't work", you need to show what you tried to do, and you need to explain what you expected, what happened, and how that didn't meet your expectations;
• Check the logs, and post log snippets if you find something you think is relevant;
• Link to some other threads that you’ve found, and tried, and explain why they didn’t help you.

If you haven't tried anything because you're not sure where to begin, the best way to learn is to experiment. Embrace failure, because it's a great learning tool. Remember you are playing with switches and lights, not launch codes for nuclear missiles, so aside from getting "that look" from your spouse, errors are unlikely to have serious consequences.

This also seems a good point for me to offer this: I wrote Reactor as a tool for you to use to solve your automation/logic problems, not as a tool for me to use to solve your automation/logic problems. I am going to increasingly leave logic-only posts that don't involve bugs or specific Reactor operational questions to the community for response. Having me answer every question doesn't improve the ability of the group; that needs to change.

Make good screen shots. If you screen shot your entire display and post it, scaling and downsampling will make it unreadable. If you zoom out your window/browser/screen to get everything in one image it will not be readable. Before taking a screen shot, un-maximize your window and reduce it to a reasonable size, and then screen shot just the window, or better still, grab the relevant rectangle where the action is (but remember, context is important, so be wary of over-cropping — a screen shot of a field with an error flag that doesn't include the condition or action type is probably over-cropped). Do not screen-shot code, log snippets, or formatted text like configs — please use fenced code blocks and paste the real code/data/text (see Format Posts Properly below).

Make good log snippets. When posting logs, always post several dozen lines before anything you find relevant, and a few lines after. Context is important. Think crime scene: it's much easier to determine what happened when a witness describes it than it is to show up to find a dead body on the floor and nobody around. All of the events and messages leading up to the entry that drew your attention may contain vital clues about what was going on to get to that condition. It is also often useful to post (in addition) the startup messages for the most recent restart of Reactor. Do not screen-shot log snippets — post the actual text in a fenced code block (see Format Posts Properly below).

Explain Your Work. It is a nightmare to see posts that contain pages of screen shots of rules and reactions, and yet have no explanation of how they are intended to solve the problem. Do not assume that just because we can read every rule and action, we can understand what that means for your system or how you're thinking about the problem and solution. With your screen shots, provide an explanation of what everything does along the way, why things are done the way they are, and what you think they are intended to do.

Format posts properly. The forums are a tool, and like any tool, you should learn to use it properly if you're going to use it frequently. Learn how to format code, inline and blocks, and use the fenced code block formatting for all code and code-like text (config/YAML, JSON, etc.) and log snippets. Improper formatting can hide errors, or make them more difficult to see. Here's a cheat-sheet for Markdown formatting; it's easy to use fenced code block formatting for code blocks and log snippets.

Redact personal information. Please remember, when posting logs or screen shots, to redact any personal information. This includes serial numbers, API keys, email addresses, lat/long of your home, etc. Remember you are posting this stuff into a public forum, to be captured by search engines and Internet archivers. Forever.

Make sense. Don't let your haste to get your question asked overwhelm good communication. Re-read your post and make sure you've addressed all of the above, and that the post is organized and makes sense. In particular, watch your antecedents. I can't tell you how many "I have two switches but when I turn it on the status doesn't change" posts I've had to straighten out before I can even start guessing what the problem is.

Use (keyword) tags. We're all not using enough keyword tags (full disclosure: I didn't even know they were possible in these forums until recently). Tags can help the search a lot. Common tags may be zwave, hass, hubitat, conditions, reactions, expressions, etc. Hubs, device types, condition or action types are all good candidates for tags. Don't use MSR, msr, or reactor as a tag unless you are posting outside of the Multi-Hub Reactor category; it isn't necessary. Everyone understands that the Reactor category contains Reactor topics/posts, and search lets you limit its breadth to specific categories, so the extra tags are just redundant. In this forum's software (NodeBB), you can enter tags in the bottom of the composer when writing/editing your topic/head post.

Don't tag people/leads in the head post. If you are starting a new topic and writing the opening post for it, and you begin it by tagging me (or whoever the lead(s) is(are) for whatever category), it comes across as bad manners and demanding of an answer. I don't know of any forum in which the category moderators aren't subscribed to their categories (I certainly am), so notifications of new topics go out automatically and such tagging is redundant.

Don't DM product questions. If you have a product question or problem, odds are someone else has or will have the same question/problem at some future date, so having the conversation recorded and searchable in the public forum threads is useful (and respectful of the time invested to help you).

Fix your topic head post. If you are asked to revise your head post because it didn't meet the above guidelines, please edit/correct the head post itself, don't post an add-on reply down below in the thread with the additions or corrections. It's important that the head posts in each topic are high quality and meet these guidelines.

Replies and Discussion

Don't non-answer or distract. If someone asks how to do something in a particular way, unless you are certain that it can't possibly be done the way they are asking, don't reply with an answer that doesn't address the method.

It's sometimes the case that when you feel a need to answer with a different method than OP has inquired about, OP's question/post is posing an X-Y Problem, and in this case, it's likely the post title and description are poor (asking about method rather than goal is a clue), so address that first (e.g. "What is it you are actually trying to accomplish?"). Then you'll have a perfect opportunity to point out different methods.

Don't "Me Too". Don't reply to just say "I'm having this problem too." You can do that if you have additional information to offer that may help in isolating a problem; that's always welcome. But if all you're saying is "me too," that's not really useful and doesn't contribute to the discussion/solution.

Don't use a non-contributing reply as a way to start watching a thread. You may find yourself interested in a thread and want to be notified when there are replies. The bad "Facebook way" is to reply "Following..." (or, again, "me too") in the thread, which makes the forums automatically subscribe you to the thread. It clogs the thread with useless replies. The preferred way is to use the "bell" icon button in the topic header to set a watch on the thread.

Tag people in discussion only when it's relevant to call their attention. Personal tagging can and should be used when mentioning others to thank them for earlier thread responses (i.e. when they are already part of the thread discussion), or add them to the discussion as a link perhaps to another thread on a similar issue going on at the same time, etc. But tagging someone to add them should be considered carefully: consider how welcome that call for attention may be, and how they may feel about the relevance of the discussion or their involvement in it.

Don't hijack or wander. Hijacking or thread-jacking is making a reply that takes the thread off topic. Instead, start a new thread and link to the related thread if there is a relevant connection.

Solved It! When your problem is solved, whether you solved it yourself or someone else did, please mark the head post title [SOLVED]. Ideally, also add a link to the end of your head post to the solution post: you can right-click on the date/time of the solution post and choose "Copy Link..." to get the link, and then paste at the end of your head post Solved here: <paste link>. If you solve your own problem, please make your own post describing what you did (and link to that in the head).

DO NOT FLAIL! If I am working with you on troubleshooting/investigation, asking you to try specific things and give me the results, do not start random experiments, change your entire approach to the problem, make changes I didn't direct, delete things, etc. At that point, I am troubleshooting and need you to be my hands and eyes. If I get the impression that you are making a moving target for me to hit, I'll just stop working with you on it. This is such a serious matter for me that repeated instances may affect your future support.

__________________________________

Inspired by this awesome post in the Home Assistant forums, which itself was inspired by this awesome post over in the OpenHAB forums.

Updated 2023-04-03