Beginner's Guide for Topic Creation

Setup, Configuration and Use Beginners
1

Dear All,

Lately I have read a lot of the beginner’s issues posted here and I found out that we lose a lot of time finding out the real problems that people are trying to solve using this forum.
@rlkoshak, @Udo_Hartmann, @Dim, @rossko57, @sihui, @ThomDietrich and many others (sorry for not mentioning you all) lose a lot of time just finding out step by step what the problem really is (sometimes I have the feeling that we are pulling teeth out of the topic’s creator’s mouth). We lose this time just because the information given is scarce, or even worse in the form (and I am not exaggerating): “openHAB stopped working after restart” with no additional information.
I kindly ask you to take a look at the guide I am trying to describe for beginners’ topic creation and improve it together with me. Maybe the forum platform will later be able to offer templates for issues.
In the beginning, a popup (I don’t know if it’s possible) with this type of guide should suffice when trying to post in the beginners’ category. Later on, guides like this can be extended per add-on, etc.

This is my first draft:

Scenario 1

We assume the poster installed java and then openHAB and he/she has issues with various components

Checklist before creating a beginner topic

You want to create the topic in the Beginners’ category, then you should follow a list of things that have to be checked before topic creation:

  • OS platform - here there should be a note on how to find the OS version, etc
  • Java platform used - use java --version to find out your java environment
  • openHAB version/release - here there should be a note on how to find the openHAB release using the karaf console
  • You read the relevant information at openHAB documentation site.
  • You are using Smarthome Designer if textual configuration is involved in the issue. - if Smarthome Designer is not installed, you should follow these steps.
  • You should prepare for upload the relevant parts of the conf files (items, rules, sitemap, services) when dealing with textual configuration files.
  • You should check the logs for errors - karaf console: log:tail

Scenario 2

We assume the poster tried to install openHAB and failed installing, starting, or configuring the startup of openHAB as a service.

Checklist before creating a beginner topic

You want to create the topic in the Beginners’ category, then you should follow a list of things that have to be checked before topic creation:

  • OS platform - here there should be a note on how to find the OS version, etc
  • Java platform used - use java --version to find out your java environment
  • You read the relevant information at openHAB documentation site.
  • You have this type of installation used: manual or automatic
  • You should check the permissions on the relevant files/services used - here there should be a how to description and what is needed.

If all these points above have been at least in a declarative manner followed by the poster, then we at least have more information than we can expect without this checklist!

It is a starting point, please feel free to contribute. I might be wrong, but I have the feeling that this might be helpful for many beginners that create topics without first checking basic stuff!

4 Likes
2

I like it but it makes me think of the old saying: “If you make something fool proof, God will make better fools.”

I believe anything short of a pre-filled out template that gets put into any new posting in the Beginner’s categories.

Some things I would like to see added to checklist when it gets written more for beginners (see below):

  • how to use code fences
  • how should posters communicate to us Item and Things defined through PaperUI? This is something I don’t think has been given a lot of thought by anyone. I’ve been asking for screenshots but I think new users are limited to just one per posting on their first few postings.

Now from a style perspective, I think this is a case where using “you” rather than the third person “the user” might be appropriate. I read it now and it can come across as being about someone else, not me personally. I would want this document to be very explicit and say" Hey you! Yes, you! Do these things before you post. When you post, include these things."

Towards that aim, I would drop the two scenarios (I don’t see a significant difference between them that can’t be handled all at once) and break it up more like:

#What to do before posting

  • read the docs: provide links to the relevant sections (e.g. “For problems with Items see the Items Docs”)
  • look in the logs for errors
  • load text configs into Designer to check for syntax errors
  • search the forum

#What to post

  • Platform
    • hardware, in particular, whether it is running off of an SD card
    • OS
    • java version
    • method of installation
    • openHAB version: easiest place to look for 2.2 SNAPSHOT going forward will be PaperUI
  • Question or problem: be detailed
  • Relevant configurations: use code fences where applicable
  • Relevant logs, particularly if there are errors: use code fences
3

Definitely agree.

I think this can help us.

Thanks for bringing this up. Indeed, explaining a newbie how to expose the json db for items and things is definitely a challenge. I will take some time to think about this!

I agree to disagree! There are patterns that appear all the time. I am not stating that we should restrict anyone, just that the templates might induce some influence on the creation of a topic.The number of scenarios should not be numerous (i think 3-4 would be enough).

The way you want to explain to newbies what they have to do before posting and what to post, might be a little complicated for them (it means we assume they already know most of the basic stuff, which is in so many cases not true).

I agree that my wording was not in anyway perfect! I will edit my post!

4

I think my main point is that having more than one scenario is no less complex but end up being way longer. And since 80%of the information we need is the same regardless of the scenario I don’t see that the scenario add much.

5

I am trying to influence an input, so we can have a faster output!. That is it! Nothing more!
About the 80% information we need, that is true! Unfortunately, we have to ask back and forth for the missing 20%!
Wouldn’t it be easier to follow a set of rules that can exonerate us of wasting valuable time in developing, and not thinking about what other people try to accomplish without having the decency of sharing their own setup?
I must have been rude in my last statement, sorry for that!

6

It’s 5am and I just woke up (with only 1 sip of my Greek coffee), so I didn’t read all of your comments :slight_smile:

Quick response:

I like very, very much the template from: https://github.com/openhab/openhab1-addons/issues/new
Maybe the solution is to use a similar template for discourse like George mentioned.

We solve problems based on experience (or common sense), so we all need more info to identify faster the root cause and suggest a resolution.

7

Hi George,

I like the templates idea; having some guidelines as to what information should (where possible) be provided would be a good thing - anyone who’s worked in software has seen the unhelpful “It doesn’t work, please fix” problem statement.

I can see @rlkoshak’s point about the two scenario’s given as an example - they would appear similar enough to be covered by a single scenario - that’s not to say there aren’t multiple scenario’s which would differ in the details required, equally we want to avoid defining specific scenario’s for every single problem that comes along…

I think 80/20 would be a good result - “you spend 20% of the time getting the first 80%” - the more fields/data you ask for the more chance you have of people not knowing the answers to them - I’ve been in this position myself - I couldn’t provide any log message for when OH2 was crashing, as I didn’t know where to look other than the logs, and I couldn’t work out how to ask the question in such a way as to get someone to answer it to help me…

At some point there remains questions that need to be asked and a problem investigated and it becomes a 2-way, back and forth process…

Cheers
James

1 Like
8

I’ve been contributing into several forums of different coding languages over the last 15 years, and this topic seems to arise every now and then. (I used to have the signature “I don’t do your homework!”).
IMHO there is no way to prevent questions that are incomplete and/or not understandable. The (newbie) user simple doesn’t have the knowledge.
We migth come up with a sophisticated template which is mandatory for all new threads. Would we want to fill that out for every new thread? If it isn’t mandatory, the newbies would not find it/use it…
Even if we have such a mandatory template, thread-hijacking would still be possible.

Me 2cents, don’t sweat it! I’ll keep on reading the posts, trying to understand and help, that way learning all the time!

1 Like
9

Not at all, it was bed time for the little one so my online time came to an end.

As am I. I still want templates. In the templates, I want links to instructions or at least instructions for how they can answer the questions in the templates. I think we are completely in agreement on this.

What I am arguing against is a template with 3-4 scenarios that requires the new user to read through a bunch of stuff to figure out which scenario applies to them, delete the rest, and then provided the asked for information. Most of the time I expect that most users will just use the first scenario every time, so why not just have one scenario and be done with it. In some cases, they may end up providing more information than we need but that really isn’t a problem as far as I’m concerned.

I think one of the keys will be providing the instructions for where/how to answer the questions inline or through links to the instructions.

I think this is addressed by the fact that when you create a new topic in the Beginner’s area the new topic gets pre-populated with the template and the user fills out the information. By having the template automatically apply they do not have to look anywhere and the mere fact that the template is there will encourage most (never all) to fill out the template as that will be easier than starting from scratch.

There is no solution that will completely solve this problem and I don’t think anyone here expects that this would solve it. But if we can easily provide some guidance to new users to help us help them perhaps we can reduce the amount of back and forth required to extract all the information we need to help the new users.

1 Like
10

Didn’t see this possibility, aggried!

11

After reading other replies, I must say that my idea based on scenarios might not work.
So, as a starting point, I think we should go with your proposed structure! I will try and post a new version today!
Who should implement the template? Any ideas?

12

@ThomDietrich I think is the designated forum guy, though Kai may need to be brought in to make the actual changes. I don’t want to bother Kai yet until we are a bit closer toa template.

13

Hello! I was summoned… reading.

3 Likes
14

Sooo great idea!

Discourse (our forum software) offers two three options I can think of:

  1. the general guidelines: https://community.openhab.org/guidelines
  2. the category “About”, e.g. About the Tutorials & Examples category
  3. the Topic Template

The first two can be modified by moderators, Topic Templates can (I don’t know why) only be modified by the Admin user (Kai).

Regarding the Topic Template: I need to warn everyone that anything added there is heavy weight. In the small text area in the bottom left you can’t see much and the fact that markdown is not interpreted doesn’t help. Look here for a bad example: https://central.owncloud.org/c/server/help

I believe the intention of @george.erhan is to add this content to “Setup, Configuration and Use”?

My suggestion would be to:

  1. In the Topic Template give a clean checklist of things a user should consider prior to posting. The whole template should span not more than 10-15 lines!
  2. Add all additional content, examples and instructions on “how to retrieve X” to the About Category article
  3. Update the guidelines if needed

The Guidelines and the About article should be the first point on the checklist.

Did I miss anything? What do you think?

15

I agree with everything but fear that putting everything in the About Category article will effectively hide that information from new users. At least we should put in the template a line saying to look to this article for instructions about how to find the relevant info.

I may be admitting too much here but I have never read the general guidlines nor the About articles for any of the categories and probably wouldn’t think to do so where I new user.

1 Like
16

like this?

me neither. However… would you read this? https://central.owncloud.org/c/server/help → New Topic

Btw. I’d love to see a short code snippet fences example at the end of template. It’s 3-4 lines and I believe this is one of the most common mistakes of users, resulting in a bad presentation of their problem.

17

Doh, you are ahead of me and I’m clearly not reading things closely today. Maybe it’s time to take a break for an hour or so.

Oh, I agree. We just need to strike a balance between being terse and easy to answer verses too wordy and complex. Either one can put us right back to playing the 20 questions game that the template is trying to solve.

I’m not sure what that balance is. Clearly, we don’t want to to go down the OwnCloud route.

1 Like
18

@george.erhan how’s your opinion about all of this? It would be incredible if you could draft the needed documents here before we can transfer them to the right places…

19

Before posting

  • Please review the Beginner’s Tutorial and User’s Guide for a solution before posting.
  • Have you looked in the forum for similar problems?
  • You should check the logs for errors. The information on how to get logs is found here
  • You should prepare for upload the relevant parts of the conf files (items, rules, sitemap, services) when dealing with textual configuration files. Use screenshots or description when using UI based configurations.
  • You are using Smarthome Designer, or the Visual Studio Code openHAB extension if textual configuration is involved in the issue. - if Smarthome Designer is not installed, you should follow these steps, or download the VS code extension from here. Load your configuration files into SmartHome Designer, to check the syntax of your configurations before posting
  • When posting, please use code fencing for the various configurations you want to post. (At the top of the editor there are the necessary tools).

Post template

  • Platform information:
    • Hardware: CPUArchitecture/RAM/storage
    • OS: what OS is used and which version
    • Java Runtime Environment: which java platform is used and what version
    • openHAB version:
  • Issue of the topic: please be detailed explaining your issue
  • Please post configurations (if applicable):
    • Items configuration related to the issue
    • Sitemap configuration related to the issue
    • Rules code related to the issue
    • Services configuration related to the issue
  • If logs where generated please post these here using code fences:
3 Likes
20

This looks good, especially if the pop-up is possible. I think that will all depend on whether Discourse supports that.

I’ve mainly some word choice comments that can be accepted or ignored as the main concept and over all structure looks good to me.

Many of the problems you have can probably have a solution here.

Please review the Beginner’s Tutorial and User’s Guide for a solution before posting

Have you looked in the forum for similar problems?

Move this to be the second bullet point.

You should prepare for upload the relevant parts of the conf files (items, rules, sitemap, services) when dealing with textual configuration files.

Identify and gather relevant parts of configuration files for posting. Use screenshots or description when using UI based configurations.

You are using Smarthome Designer if textual configuration is involved in the issue. - if Smarthome Designer is not installed, you should follow these steps.

If you are seeing parsing errors or “not found” errors in your logs load your configuration files into SmartHome Designer to check the syntax of your configurations before posting

If possible it would be great to include a screenshot of the buttons. Also, it is worth noting that these buttons do not appear when posting from the mobile version of the forum.

Hardware: CPU/RAM/storage

I would strike the CPU/RAMP/storage part. It is really sufficient if they just say "Raspberry Pi 3, VM on ESXi, old laptop, etc.). I can’t think of the last time knowing what the GHz of the CPU help me solve a user’s problem.

Java platform used: which java platform is used and what version

I think we should use the proper term here: Jave Runtime Environment

One other problem we may run into is for new users they have a character limit for new posts. If we start to run into problems where what we are asking for causes new users to break that limit regularly we may have to cut back on the amount of information requested.