How to ask a good question / Help Us Help You

@vzorglub

Perhaps you also could mention these two interactive tutorials with discobot .

There is one for “new users” and one for “advanced users”. I did them both and they were really helpful. :slight_smile:

1 Like

Hello @jhoney
How is this lat post relevant to this thread?

You usually start a new thread to post a question. You then are assured to be on-topic. Hopping on to somebody else’s thread is discouraged and usually considered rude.

Thus is the path to true wizardry!

:smiley:

1 Like

@TRS-80 seconds the motion for “Rich, the King of the Forums”, and then…

1 Like

Bump for @vzorglub… I think this would be very useful to get in front of new users. We should add something about code fences and anything else missing from this tutorial. FYI, the instructions in the OP of the tutorial topic are incorrect… PM @discobot with start tutorial or start advanced tutorial.

1 Like

Here is the code fence link I usually use.

How to use code fences - Tutorials & Examples - openHAB Community

I have made the post a wiki, please feel free to edit

2 Likes

I will update the OP to include a reference to the tutorial, but is there a way to edit the tutorial to include a lesson for code fences?

1 Like

I did some brief searching and it looks like customizing the overall flow is not yet implemented, or if it is implemented there is no documentation I can find for how to do it. Just about everything else can be customized by an admin (i.e. it would take Kai to add it). It might be possible to add the text or a link tutorial to one of the existing flows but I don’t see a way where we could add it and a test that the user did it right. It’s better than nothing though.

Anyone have a suggestion where in the flow it would be best to add it? https://blog.discourse.org/2017/08/who-is-discobot/ has the easiest follow details for how to customize it that I was able to find.

1 Like

If you want a real discobot tutorial about code fences it’s a bit tricky. Involves custom db query yada yada.
However we could “hijack” the already existing tutorial and add text about code fences.

See:

EDIT:

Oh well did not read properly. :roll_eyes:
I propose to add the code-fence tutorial with the quote tutorial

1 Like

I’ve only asked a couple of questions and so far I’ve gotten some pretty quick and friendly help. I read this article about good questions and since I’m really new, but an old programmer, I’d like to make a few comments and ask a couple of questions of the leadership community.

My observations are much like Rich said, sometimes you get the right answer and sometimes the wrong answer. Having led R&D organizations that selected open source components and freeware and I can honestly say the money saved never approached the cost of the subsequent headaches over commercial solutions. The word hobby was used and that is what this is for me now and presumably many people, so it is OK.

My second comment comes from my past. Having inherited an IT department while leading R&D I soon realized that the massive amount of people needed to support our infrastructure was our own making! I initiated a plan to reduce the size from 25 to 5. My discoveries led me to the realization that poorly documented solutions forced an abundance of “help” needs (translate: easier to call). By sorting the high running rate requests and beefing up the documentation with examples and how-to’s, help calls dropped rapidly. It was also an eye opening exposer to my own product documentation leading to a reduction in my customer service desk.

Someone pointed out that helpdesk people get paid and this forum is free and voluntary, so the approach could never work. However, many volunteer entities accomplish significant results when coordinated.

It does lead me to a question I couldn’t find an answer too. I see there is Board but I didn’t find a steering committee for the distribution of information? From my brief browsing of the forum, there are clearly some experts. Sadly, I’ve seen some experts answering the same questions many times like my helpdesk example. They have even commented on the problem.

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?

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.

I for one would be willingly to add my expertise to a finite initiative in that direction. I suspect, but can’t honestly speak for others, that they would be willing to document once rather than answer 10 times. I’m really not sure and don’t want to offend anyone. This is my first foray into open/free SW as a user, and maybe the general consensus is this is part of the fun of a hobby. I personally don’t think that because the posts are riddled with “help#$%#@”

Anyway, sorry for the long read. I’m just asking a couple of historians to maybe let me know what has transpired and/or if anyone has ever thought, or discussed something similar.

Thanks in advance
Cliff

Th official documentation written by the developers is very good but people do not look before they post their problem with no helpful information to solve.

There is also this little used area, based on the forum.

Thanks, didn’t know about the other how-tos. I can’t speak for the other people, I’ve spent weeks looking at the documentation. I’ll give you and example. There are numerous examples of cron statements. You can find them everywhere on the forum.

In fact, although the cron syntax is correct, I would prefer a more simple one: “0 0/5 * * * ?” //every 5 Minutes “0 1 0 * * ?” //daily at 12:01 am “0 1 0 1 * ?” //monthly at 01 12:01 am “0 2 0 1 1 ?” //yearly at 01-01 12:02 am year is optional, * is “don’t care”, ? is mandatory either on da…***

However, I was unable to get any cron job to work until I found out that there are “7” fields in the statement, not 6. This may be unique to openhabian, but it wasted countless hours for me. Even on the same page there are examples of 6 and 7. One may say the last is optional, but only the 7 would work for me.

There isn’t one.

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.

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.

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.

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.

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

1 Like

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.

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.

1 Like

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

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

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. :slight_smile:

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).

4 Likes