How to ask a good question / Help Us Help You

[rlkoshak (Rich Koshak)]

@cdstaley

I see there is Board but I didn’t find a steering committee for the distribution of information?

There isn’t one.

@cdstaley

My question goes out to the few leaders. Has there ever been a concerted effort to “organize” the forum’s content that goes beyond individual contribution. One that might shorten the learning curve, coagulate information in digestible chunks, and thus reduce the post/reply to the exceptions, not the basics?

Yes and the result is the main docs, which as Bruce points out far too few consult before asking on the forum. We’ve also created a template to fill out in some categories and created lots and lots of posts which provide the answers to commonly asked questions. We tried creating a FAQ post awhile back but it wasn’t really populated nor used.

Even a post like the OP is frankly an attempt to herd cats. Users are going to read the docs or not read the docs and will do what they do. and get mad at us for asking them to read stuff already written instead of rewriting a custom response just for them.

@cdstaley

Has there ever been a consideration to “increase” the membership cost to support a “coordinator” of volunteers. To examine where the holes are and to initiate a voluntary “enhancement” of the website and the content.

The way the openHAB Foundation is incorporated in Germany as a specific type of non-profit, I don’t think they would be allowed to hire such a person. But there are several who contribute to and coordinate contributions to the docs. @Confectrician is the primary lead on that front right now.

But it’s also important to realize we are in a state of transition. Work on OH 2.x core is done and OH 3 is the main focus. OH 3 is going to require a significant if not complete rewrite of the docs. And since we have no idea what OH 3 will actually be or how it will work, we have to wait before we can initiate that effort.

@cdstaley

I suspect, but can’t honestly speak for others, that they would be willing to document once rather than answer 10 times.

What I do and what I encourage other forum helpers to do is if you answer the same question more than a couple of times, create a new post that is easily findable and link to that post for subsequent answers. Once that post has seen some exposure and been polished, consider moving the contents to the docs.

@cdstaley

There are numerous examples of cron statements. You can find them everywhere on the forum.

But did you look in the docs? Here is the docs for cron triggers.

A cron expression takes the form of six or optionally seven fields:

1. Seconds
2. Minutes
3. Hours
4. Day-of-Month
5. Month
6. Day-of-Week
7. Year (optional field)

for more information see the Quartz documentation.

You may also use CronMaker or the generator at FreeFormatter.com to generate cron expressions.

It clearly states how many fields there are and even provides a link to a tool to help you generate the expression you are after.

This kind of leads back to me initial answer and Bruce’s comments. Almost all of the stuff that people struggle with are actually documented in the docs, sometimes in great detail. But far too often users don’t think to look there or don’t bother to.

Now, if there is anything unclear about the docs I quoted above, we more than welcome contributions, updates, and suggestions for improvement. There is a link at the bottom of the page that will take you straight to the form on GitHub where you can edit the source and create a PR to be added to the docs.

[cdstaley (Clifford Staley)]

Rich, you have been very nice and I really appreciate the time you take to answer mine and other peoples questions. I don’t want to piss anyone off and was only exploring my personnel perceptions on things I’ve seen.
I’ve read, and read and read the docs. Be it I’m stupid, which is always a possibility, or I’m just old and missing the subtleties but the experience has been hard. It shouldn’t be that hard for a guy with MS in CS. Here’s an example to follow up on cron. In the Quartz docs is states 6 not 7, but to your point, the OpenHAB docs state 7.

CronTrigger Example 1 - an expression to create a trigger that simply fires every 5 minutes
“0 0/5 * * * ?”
CronTrigger Example 2 - an expression to create a trigger that fires every 5 minutes, at 10 seconds after the minute (i.e. 10:00:10 am, 10:05:10 am, etc.).
“10 0/5 * * * ?”

I poured over this document and looked at many posts. I got the same reference to this in another place so that is what I tried. In all fairness, I didn’t just post a question.

Another example is the documents often give parametric values but not a clear place to put them. I often see people ask the same questions.

I’m sure that my skills are a little rusty. That this in no way is plug and play. I was just exploring what has happened before and if anyone had tried something else. It’s good to know that 3.0 is coming this way. There is a lot of info in the docs and if the structure of OH changes significantly it will be a big job.

Like I said, this is my first time sticking my toe in the water. My first attempt at home automation was back in 1979 when I ran an open loop op amp at 1,000,000 gain to detect people moving in a room. Then x10 which I’ve still got in use via insteon but never liked the cloud based solution and wanted a GUI. so…

Thanks again for your quick and concise responses.

Cliff

[rlkoshak (Rich Koshak)]

@cdstaley

I poured over this document and looked at many posts. I got the same reference to this in another place so that is what I tried. In all fairness, I didn’t just post a question.

Did you go to the cron builder tool linked to in the docs? It’s a great too that can go both directions (i.e. explain a given cron expression or let you fill out a form and create a valid cron expression).

I’m not saying you didn’t search and didn’t try but it sounds like you are proposing that we go through all the effort to build a parallel set of docs on the forum. That’s just not feasible. There is one and only one source for complete (as complete as we can make it) and accurate information and that’s the docs. If there is something wrong in the docs or something unclear in the docs, than the docs need to be improved. And that happens when people contribute to them.

The docs are as good as we can make them. If they are not adequate, than someone who can do better needs to step up and fix them.

@cdstaley

Another example is the documents often give parametric values but not a clear place to put them. I often see people ask the same questions.

We do not have the man power to build an maintain duplicate documentation. So we have generic docs that define in general where stuff goes and the syntax and specific documentation (e.g. where and what to put in to configure InfluxDB Persistence). We can’t afford the manpower to duplicate the several pages of “here’s how to configure Persistence” in the specific docs for each of the dozen or so persistence addons. The same goes for everything else. It may be suboptimal from the user’s perspective but it’s the best we can provide.

But also realize, when we respond with a link to the docs, it’s not to be mean or to say “RTFM”. We are aware that the docs are complex and hard to follow. You likely just missed the section that has your answer or didn’t realize it’s import.

[cdstaley (Clifford Staley)]

Thanks for your responses. Sorry I’m not clearer. I’m not asking for parallel docs. I’m really not asking for anything other than a little insight into how things work. It’s clear to me you are one of the foundational components to this endeavor. My goal was not to come across as a complainer. I appreciate your perspective and hope I didn’t alienate anyone. You’ve been more than generous with your time!

I was trying to learn if there was any initiative heading in the direction I mentioned. If there was, I was willing to get involved, step up as you said. Seeing how I have “virgin” eyes and a track record of multiple successful start-up companies from $3m - $3.2B, I have skills that could potentially help.

I’m new to this type of SW development so I was just exploring with the goal of helping to make it better. That was the root of my inquire. I did ask if there was an effort… I get it, people like yourself have been doing what you have been doing for a long time and some newbie comes along so a natural reaction is WTF.

Again, I apologize to everyone I might of offended. I’ll crawl back in my hole and keep plugging away.

Thanks again for you candor and insight. Hope to stay in touch as my understanding grows.
cds

[rlkoshak (Rich Koshak)]

@cdstaley

It’s clear to me you are one of the foundational components to this endeavor.

Nah, I just help out on the forums. I don’t even contribute to the overall docs as much as I probably should.

@cdstaley

I was trying to learn if there was any initiative heading in the direction I mentioned. If there was, I was willing to get involved, step up as you said. Seeing how I have “virgin” eyes and a track record of multiple successful start-up companies from $3m - $3.2B, I have skills that could potentially help.

There will be quite a concerted effort in the lead up to OH 3 to write/rewrite docs. There will be lots of rules docs to write, tutorials, a brand new UI and who knows what else. As soon as we know enough about where OH 3 is going I expect a team will self form (it’s all volunteer driven) to try and pound out some docs.

FOSS projects in general and openHAB in general is entirely a ground up endeavor. If something gets done, it’s because someone volunteered their time and started work on it. No one can tell anyone else what to work on so development is uneven. Code/docs speaks way louder than forum postings or someone shouting “do this, not that”. People are gonna work on what they want to when they want to. That doesn’t mean there is no direction, but it also means some important things never get done and some unimportant things (in some people’s opinions) get done instead. Helping out on the forum is an excellent way to contribute. Home automation is hard. openHAB is hard. Even the experts and old timers need help sometimes. And helping others solve their problems gives you valuable experience to solve your own.

No offence was taken and we welcome any and all contributions in any form. But you have to look to find a place that you can contribute on your own. There is no one who’s going to tell you what to work on and you will not be able to tell anyone else what they should work on. Personally, I choose to contribute by answering forum posts and doing a smattering of docs here and there as I have the need (e.g. recently I wanted to use the new Ephemeris feature in OH 2.5 but there were no docs written yet so I figured out how it works with the help of the developers and wrote the docs).